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Introduction 


What is SunView? 

SunView is a system to support interactive, graphics-based applications running 
within windows. It consists of two major levels of functionality: the application 
level and the system level. The system level is described in this document and 
covers two major areas: the building blocks on which the application level is 
built and advanced application-related features. 

Changes From Release 2.0 

SunView is an extension and refinement of SunWindows 2.0, containing many 
enhancements, bug fixes and new facilities not present in SunWindows. How¬ 
ever, the changes preserve source level compatibility between SunWindows 2.0 
and SunView. 

Organization of 

Documentation 

These changes are reflected in the current organization of the SunView documen¬ 
tation. The material on Pixrects from the old SunWindows Reference Manual is 
in a new document titled Pixrect Reference Manual, uch of the functionality of 

The 2.0 SunWindows Reference 

Manual has not been reprinted for 
SunView. 

the SunWindows window and tool layers has been incorporated into the new 
SunView interface. The basic SunView interface, intended to meet the needs of 
simple and moderately complex applications, is documented in the application- 
level manual, the SunView 1 Programmer’s Guide. 

This document is the SunView 1 System Programmer’s Guide. It contains a com¬ 
bination of new and old material. Several of its chapters document new facilities 
such as the Notifier, the Agent, the Selection Service and the defaults package. 
Also included is low-level material from the old SunWindows Reference Manual 
— e.g. the window manager routines — of interest to implementors of window 
managers and other advanced applications. 

This document is an extension of the application-level manual. You should only 
delve into this manual if the information in the SunView 1 Programmer's Guide 
manual doesn’t answer your needs. Thus, you should read the application-level 
manual first. 

Compatibility 

Another consideration is compatibility with future releases. Most of the objects 
in the SunView 1 Programmer’s Guide are manipulated through an opaque attri¬ 
bute value interface. Code that uses them will be more portable to future ver¬ 
sions of SunView than if it uses the routines documented in this manual which 
assume particular data structures and explicit parameters. If you do use these 
routines then the code should be encapsulated so that low-level details are 
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Keep your old documentation 


Changes in Release 4.0 


isolated from the rest of your application. 

On the way to SunView, we have discarded documentation about the internals of 
some data structures that were discussed in SunWindows 2.0. In addition, we 
have discarded documentation about routines whose functionality is now pro¬ 
vided by the interface discussed in the SunView 1 Programmer’s Guide. Thus, if 
your application is based on the SunWindows programming interface, you should 
keep your 2.0 documentation. In particular, the following structures are no 
longer documented (there may by others): tool, pixwin, toolsw, and 
toolio. 

SunOS Release 4.0 includes further enhancements to the higher-level SunView 
programmatic interface documented in the SunView 1 Programmer’s Guide, such 
as alerts, shadowed subframes, ‘Props’ actions, and so on . Sun encourages pro¬ 
grammers to use these higher-level interfaces in preference to low-level routines 
documented in this manual whenever possible; this will help to insulate your 
applications from changes in the low-level window-system interfaces underneath 
SunView. 
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Overview 


2.1. Sun View Architecture From a system point of view, SunView is a two-tiered system, consisting of the 

application and system layers: 

□ The application layer provides a set of high-level objects, including windows 
of different types, menus, scrollbars, buttons, sliders, etc., which the client 
can assemble into an application, or tool. This layer is sometimes referred to 
as the tool layer. The functionality provided at this level should suffice for 
most applications. This layer is discussed in the SunView 1 Programmer’s 
Guide. 

□ At the system layer a window is presented not as an opaque object but in 
terms which are familiar to UNIX programmers — as a device which the 
client manipulates through a file descriptor returned by an open (2) call. 

This layer is sometimes referred to as the window device layer. The manipu¬ 
lation and multiplexing of multiple window devices is the subject of much 
of this document. The term “window device” is often shortened to just 
window in this document. 

2.2. Document Outline This document covers the follow system level topics: 

□ A system model which presents the levels, components and inter¬ 
relationships of the window system. 

□ A SunView mechanism, called the Agent, which includes: 

• notification of window damage and size changes. 

• reading and distribution of input events among windows within a pro¬ 
cess. 

• posting events with the Agent for delivery to other clients, 
p Windows as devices, which includes: 

• reading control options such as asynchronous input and non-blocking 
input. 

o The screen abstraction, called a desktop, which includes: 

• Routines to initialize new screens so that SunView may be run on them. 

• Multiple screens accessible by a single user. 
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□ The global input abstraction, called a workstation, which includes: 

• environment wide input device instantiation. 

• controlling a variety of system performance and user interface options. 

• extending the Virtual User Input Device interface with events of your 
own design. 

□ Advanced use of the general notification-based flow of control management 
mechanism called the Notifier, which includes: 

• detection of input pending, output completed and exception occurred on 
a file descriptor. 

• maintenance of interval timers. 

• dispatching of signal notifications. 

• child process status and control facilities. 

• a client event notification mechanism, which can be thought of as a 
client-defined signal mechanism. 

□ The Selection Service, for exchanging objects and information between 
cooperative client, both within and between processes. 

□ The defaults mechanism, for maintaining and querying a database of user- 
settable options. 

□ Advanced imaging topics, which include: 

• the repair of damaged portions of your window, when not retained. 

• receiving window damage and size change notifications via 
SIGWINCH. 

□ The mechanisms used to violate window boundaries. You would use them if 
you created a menu or prompt package. 

o Routines to perform window management activities such as open, close, 

move, stretch, top, bottom, refresh. In addition, there are facilities for invok¬ 
ing new tools and positioning them on the screen. 

□ Routines to manipulate individual rectangles and lists of rectangular areas. 
They forms what is essentially an algebra of rectangles, useful in computing 
window overlap, points in windows, etc. 

□ Advanced icon topics, including displaying them, accessing them from a 
file, their internal structure, etc.. 

□ Advanced scrollbar topics, including calculating and performing your own 
scroll motions (in a canvas, for example). 

Finally, there is an appendix on how to write a line discipline for a new input 
device that you want to access through SunView. Another appendix covers some 
programming notes. 
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SunView System Model 


3.1. A Hierarchy of 
Abstractions 


This chapter presents the system model of SunView. It discusses the hierarchy of 

abstractions that make up the window system, the data representations of those 

abstractions and the packages that manage the components. 

There is a hierarchy of abstractions that make up the window system: 

• Tiles are used to tile the surface of a window. Tiles don’t overlap and may 
not be nested. For example, a text subwindow with a scrollbar is imple¬ 
mented with separate tiles for both the scrollbar and the text portion of the 
subwindow. 

• Windows are allowed to overlap one another 1 and may be arbitrarily nested. 
Frames, panels, text subwindows, canvases and the root window are all 
implemented as windows. 

• Screens, sometimes called desktops, support multiple windows and represent 
physical display devices. A screen is covered by the root window. 

• Workstations support multiple screens that share common user input devices 
on the behalf a single user. For example, one can slide the cursor between 
screens. 

The figure below shows the hierarchy: 


' The procedure which lays out subwindows of tools does it so they do not overlap, but this is not an 
inherent restriction. 
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Figure 3-1 SunView System Hierarchy 
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Data Managers 


Data Representations 


3.2. Model Dynamics 


The various parts of the system support the management of this hierarchy. They 

provide the glue between the various components: 

• The window driver, (currently) residing in the UNIX kernel as a pseudo dev¬ 
ice driver that is accessed through library routines, supports windows, 
screens and workstations. 

• The pixwin library package allows implementors of specific windows and 
tiles to access the screen for drawing. 

• The Notifier library package is used to support the general flow of control to 
multiple disjoint clients. 

• The Agent library package can be viewed as the SunView-specific extension 
of the Notifier. The Agent supports tiles and windows. 

• The Selection Service is a separate user process that supports the inter¬ 
process communication and control of user selection related data. In this 
role it essentially supports specific tile implementations. 

This conceptual model is useful to understand the structure and workings of the 

system. However, the model doesn’t always translate into corresponding objects: 

• Tiles are implemented as opaque handles with pixwin regions used to com¬ 
municate the size and position of the tile to the Agent. 

• At the system level, windows are implemented as UNIX devices which are 
represented by file descriptors. Window devices are not to be confused with 
the application level notion of windows which are opaque handles. A file 
descriptor is returned by open(2) of an entry in the /dev directory. It is 
manipulated by other system calls, such as select(2), read(2), 
ioctl(2), and close(2). 

• There is a screen structure that describes a limited number of properties of a 
desktop. However, it is a window file descriptor that is used as the “ticket” 
into the window driver to get and set screen related data. This is possible 
because a window is directly associated with a particular screen. 

• There is no system object that translates into a workstation. However, like 
desktop data, workstation-related data is accessed using a window file 
descriptor. Again, this is because a window is directly associated with a par¬ 
ticular screen which is directly associated with a particular workstation. As 
a side effect of this association, one can use the file descriptor of a panel and 
asked about workstation related data for the workstation on which the panel 
resides. 

Now that you have been introduced to the players in the window system, let’s see 

how they interact. 
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Tiles and the Agent 


Windows 


Tiles are quite simple and “lightweight” abstractions. The main reason for hav¬ 
ing tiles instead of yet another nesting of windows is that file descriptors are rela¬ 
tively heavyweight. There can only be 64 file descriptors open per UNIX process 
in Sun’s release 4.0. As a result, a tile provides only a subset of the functionality 
of a full-blown window. After telling the Agent that a tile covers a certain por¬ 
tion of the window, the Agent provides the following services: 

• The Agent tells you when your tile has been resized. 

• The Agent tells you when your tile should be repainted. Optionally, you can 
tell the Agent to maintain a retained image for your tile from which the 
Agent can handle the repainting itself. 

• The Agent reads input for the tile’s window and distributes it to the 
appropriate tile. 

• The Agent notices when tile regions have been entered and exited by the 
cursor and notifies the tile. 

In addition, the Agent is the conduit by which client generated events are passed 
between tiles. For example, when the scrollbar wants to tell a canvas that it 
should now scroll, the communications is arranged via the Agent. The Agent, in 
turn, uses the Notifier to implement the data transfer. 

It is your responsibility to lay out your window’s tiles so that they don’t overlap, 
even when the window size changes. 

Even a window with only a single tile that covers its entire surface may use the 
Agent and its features. 

Windows are the focus of most of the functionality of the window system. Here 
is a list of the information about a window maintained by the window system: 

• A rectangle refers to the size and position of a window. Some windows 
(frames) also utilize an alternative rectangle that describes the iconic posi¬ 
tion of a window. 

• Each window has a series of links that describe the window’s position in a 
hierarchical database, which determines its overlapping relationships to 
other windows. Windows may be arbitrarily nested, providing distinct 
subwindows within an application’s screen space. 

• Arbitration between windows is provided in the allocation of display space. 
Where one window limits the space available to another, clipping, guaran¬ 
tees that one does not interfere with the other’s image. One such conflict 
arises when windows share the same coordinates on the display: one over¬ 
laps the other. Thus, clipping information is associated with each window. 

• When one window impacts another window’s image without any action on 
the second window’s part, the window system informs the affected window 
of the damage it has suffered, and the areas that ought to be repaired. To do 
this the window system maintains a description of the portion of the window 
of the display that is corrupted as well as the process id of the window’s 
owner. 
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• On color displays, colormap entries are a scarce resource. When shared 
among multiple applications, they become even more scarce: there may be 
simultaneous demand for more colors than the display can support. Arbitra¬ 
tion between windows is provided in the allocation of colormap entries. 
Provisions are made to share portions of the colormap (colormap segments). 
There is colormap information that describes that portion of the colormap 
assigned to a window. 

• Real-time response is important when tracking the cursor, so this is done by 
the window system. Thus, the image (cursor and optional cross hairs) used 
to track the mouse when it is in the window is part of the window’s data. 2 

• Windows may be selective about which input events they will process, and 
rejected events will be offered to other windows for processing; you can 
explicitly designate the window rejected events are first offered to. 3 A mask 
indicates what keyboard input actions the window should be notified of and 
there is a similar mask for pick/locator-related actions. 

• A window device is read in order to receive the user input events directed at 
it. So like other input devices a window supports a variety of the input 
modes, such as blocking or non-blocking, synchronous or asynchronous, etc. 
In addition, there is a queue of input events that are pending for a window. 

• There are 32 bits of data private to the window client stored with the win¬ 
dow. 



Desktop 


Desktop data relates to the physical display: 


• The physical display is associated with a UNIX device. The desktop main¬ 
tains the name of this device. 

• The desktop maintains the notion of a default foreground and background 
color. 

• The desktop records the size of the screen. 

• The desktop maintains the name of the distinguished root window on itself. 

• When multiple screens are part of a workstation, each desktop knows the 
relative physical placement of its neighboring displays so that the mouse 
cursor may slide between them. 


2 There is only one cursor per window, but the image may be different in different tiles within the window 
(e.g. scrollbars have different cursors). If so, the different cursor images are dynamically loaded by the user 
process and thus real time response is not assured. 

3 Not all events are passed on to a designee, for example window-specific events such as LOC WINENTER 
and KBD_REQUEST are not. 
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Locking 
Display Locking 


Window Database Locking 


Colormap Sharing 


The desktop also arbitrates screen surface access and window database manipula¬ 
tion. 

Display locking prevents window processes from interfering with each other in 
several ways: 

• Raster hardware may require several operations to complete a change to the 
display; one process’ use of the hardware is protected from interference by 
others during this critical interval. 

• Changes to the arrangement of windows must be prevented while a process 
is painting, lest an area be removed from a window as it is being painted. 

• A software cursor that the window process does not control (the kernel is 
usually responsible for the cursor) may have to be removed so that it does 
not interfere with the window’s image. 

Window database locking is used when doing multiple changes to the window’s 
size, position, or links in the window hierarchy. This prevents any other process 
from performing a conflicting modification and allows the window system to 
treat changes as atomic. 


On color displays, colormap entries are a limited resource. When shared among 

multiple applications, colormap usage requires arbitration. Consider the follow¬ 
ing applications running on the same display at the same time in different win¬ 
dows: 

• Application program X needs 64 colors for rendering VLSI images. 

• Application program Y needs 32 shades of gray for rendering black and white 
photographs. 

• Application program Z needs 256 colors (assume this is the entire colormap) 
for rendering full color photographs. 

Colormap usage control is handled as follows: 

• To determine how X and Y figure out what portion of the colormap they 
should use (so they don’t access each others’ entries), the window system pro¬ 
vides a resource manager that allocates a colormap segment to each window 
from the shared colormap. To reduce duplicate colormap segments, they are 
named and can be shared among cooperating processes. 

• To hide concerns about the correct offset to the start of a colormap segment 
from routines that access the image, the window system initializes the image 
of a window with the colormap segment offset. This effectively hides the 
offset from the application. 

• To accommodate Z if its large colormap segment request cannot be granted, 
Z’s colormap is loaded into the hardware, replacing the shared colormap, 
whenever the cursor is over Z’s window. Z’s request is not denied even 
though it is not allocated its own segment in the shared colormap. 
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Workstations 


The domain of a workstation is to manage the global state of input processing. 
User inputs are unified into a single stream within the window system, so that 
actions with the user input devices, usually a mouse and a keyboard, can be coor¬ 
dinated. This unified stream is then distributed to different windows, according 
to user or programmatic indications. To this end a workstation manages the fol¬ 
lowing: 

• A workstation needs some number of user input devices to run. A dis¬ 
tinguished keyboard device and a distinguished mouse-like device are recog¬ 
nized since these are required for a useful workstation. Non-Sun supported 
user input devices may be used as these distinguished devices. 

• Additional, non-distinguished user input devices, may be managed by a works¬ 
tation as well. 

• The input devices associated with the workstation are polled by the window 
system. Locator motion causes the cursor to move on the screen. Certain 
interrupt event sequences are noted. Events are timestamped enqueued on the 
workstation’s input queue based on the time they were generated. 

• This input queue is massaged in a variety of ways. If the input queue becomes 
full, locator motion events on the queue are compressed in order to reduce its 
size. In addition, locator motion at the head of the queue is (conditionally) 
collapsed so as to deliver the most up-to-date locator position to applications. 

• Based on the state of input focuses and window input masks a window is 
selected to receive the next event from the head of the input queue. The event 
is placed on the window device’s separate input pending queue and the 
window’s process is awoken. 

• The workstation uses a synchronized input mechanism. The main benefit of a 
synchronized input mechanism is that it removes the input race conditions 
inherent in a multiple process environment. While a window processes the 
input event the workstation waits for it to finish before handing out the next 
event. 

• The workstation deals with situations in which a process takes too long to 
finish processing an input event by pressing on ahead in a partially synchron¬ 
ized mode until the errant process catches up to the user. This prevents a mis¬ 
behaving process from disabling user interaction with other processes. 
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The Agent & Tiles 


This chapter describes how to utilize the Agent to manage tiles for you. It con¬ 
tains the implementation details associated with tiles and the Agent, as intro¬ 
duced in the SunView System Model chapter. This chapter uses a text subwindow 
with a scrollbar as an example of Agent utilization.^ 

4.1. Registering a Tile With The Agent is a little funny in that you don’t ask it to create a tile for you that it 
the Agent will then manage. In fact tiles are only abstractions. Instead, you create a pixwin 

region and a unique client object and pass these to the Agent to manage on your 
behalf. The following routine is how this registration is done. 

int 

win_register(client, pw, event_func, destroy_func, flags) 


Notify_client 

client; 

Pixwin 

*pw; 


Notify_func 

event 

func; 

Notify_func 

destroy__func; 

u_ji.nt 

flags; 


#define PW_RETAIN 


Oxl 

#define PW_FIXED_IMAGE 

0x2 

♦define PW_INPUT DEFAULT 

0x4 

♦define PW_NO_LOC_ 

ADJUST 

0x8 

♦define PW REPAINT 

ALL 

0x10 


client is the handle that the Agent will hand back to you when you are 
notified of interesting events (see below) by a call to the event_f unc function, 
client is usually the same client handle by which a tile is known to the 
Notifier. Client handles needs to be unique among all the clients registered with 
the Notifier. 

pw is a pixwin opened by client and is the pixwin by which the tile writes to 
the screen. This pixwin could have been created by a call to pw_open () if the 
window has only a single tile that covers its entire surface. More often the tile 
covers a region of the windows created by a call to pw_region (), documented 
in the Clipping with Regions section of the Imaging Facilities: Pixwins chapter 

4 The header file /usr/ include / sunwindow/window_hs .h contains the definitions for the routines 
in this chapter. 
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Laying Out Tiles 


of the SunView 1 Programmer’s Guide. Regions are themselves pixwins that 
refer to an area within an existing pixwin. 

flags control the options utilized by the Agent when managing your tile: 

□ PW_RETAIN — Your tile will be managed as retained. This means that the 
window system maintains a backup image of your tile in memory from 
which the screen can be refreshed in case the tile is exposed after being hid¬ 
den. 

o PW_FIXED_IMAGE — The underlaying abstraction of the image that your 
tile is displaying is fixed in size. This means that the client need not be 
asked to repaint the entire tile on a window size change. Only the newly 
exposed parts need be repainted. 

□ PW_INPUT_DEFAULT — Usually, the cursor position over a tile indicates 
which tile input will by sent to. However, if your window has the keyboard 
focus, the cursor need not be over any tile in your window in order for the 
window to be sent input. The tile with this flag on will receive input if the 
cursor is not over any tile in the window. In our example, the text display 
tile would be created with this flag on because it is the main tile in the win¬ 
dow. 

□ PW_NO_LOC_AD JUST — Usually, when the Agent notifies your tile of an 
event the locator x and y positions contained in your event are adjusted to be 
relative to the tile’s upper left hand comer. Turning this flag on suppresses 
this action which means that you’ll get events in the window’s coordinate 
space. 

□ PW_REPAINT_ALL — Setting this flag causes your tile to be completely 
repainted when ever the Agent detects that any part of your window needs to 
be repainted. 

event_f unc is the client event notification function for the tile and 
destroy_f unc is the client destroy function for the tile. The Agent actually 
sets these functions up with the notifier (see the Notifier chapter in the SunView 1 
Programmer’s Guide for a discussion of these two types of notification functions 
and their calling conventions). In addition, the Agent gets input pending and 
SIGWINCH received (used for repaint and resize detection) notifications from the 
notifier and posts corresponding events to the appropriate tile. Tiles in the same 
window need to share the same input pending notification procedure because 
input is distributed from the kernel at a window granularity. Tiles also share the 
same input masks, as well as other window data. 

Tiles are used to tile the surface of a window. Tiles may not overlap and may not 
be nested. As an example, a text subwindow with a scrollbar is implemented 
with a separate tile for both the scrollbar and the text portion of the subwindow. 

It is a window owner’s responsibility to layout tiles so that they don’t overlap. 
The Agent does nothing for you in this regard, so layout is arranged via conven¬ 
tions among tiles. In our example, there are two tiles, the scrollbar and a text 
display area. Here is how layout works when scrollbars are involved: 
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Dynamically Changing Tile 
Flags 



□ The text subwindow code creates a vertical scrollbar. The scrollbar code 
looks at the user’s scrollbar defaults and finds out what side to put the 
scrollbar on and how wide it should be. Given this information it figures out 
where to place its tile. The scrollbar code registers its new tile with the 
Agent. 

□ After creating the scrollbar, the text subwindow code asks the scrollbar what 
side it is on and how thick it is. Given this information the text subwindow 
figures out where to place its text display tile. The text subwindow code 
registers its new tile with the Agent. 

□ When a window resize notification (sent by the Agent) is received by the 
scrollbar it knows to hug the side that it is on as it adjusts the size of its 
region. A similar arrangement is followed by the text display tile. 

The following routine lets you dynamically set the tile’s flags: 

int 

win_set_flags(client, flags) 

Notify_client client; 
u_int flags; 

A —1 is returned if client is not registered, otherwise 0 is returned. 

When you set a single flag, it is best to retrieve the state of all the flags first and 
then operate on the bit that you are changing, then write all the flags back; other¬ 
wise, any other flags that are set will be reset. The following routine retrieves the 
current flags of the tile associated with client: 

u_int 

win_get_flags(client) 

Notify_client client; 


Extracting Tile Data Extraction of interesting values from clients of the Agent is done via the follow¬ 

ing calls: 

int 

win_get_fd(client) 

Notify_client client; 

win_get_f d () gets the window file descriptor associated with client’s tile. 
Pixwin * 

win_get_pixwin(client) 

Notify_client client; 

win_get_pixwin () gets the pixwin associated with client’s tile. 

Once you register your tile with the Agent, the Agent causes the event_f unc 
you passed to win_register () to be called (“notified”) to handle events. 
You must write your tile’s event notification procedure yourself; the events it 
might receive are listed in the Handling Input chapter in the SunView 1 
Programmer’s Guide. 


4 . 2 . Notifications From the 
Agent 
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The calling sequence for any client event notification function is: 

Notify_value 

event_func(client, event, arg, when) 

Notify_client client; 

Event *event; 

Notify_arg arg; 

Notify_event_type when; 

client is the client handle passed into win_register (). event is the 
event your tile is notified of. arg is usually NULL but depends on 
event_id (event ). In the case of the scrollbar tile notifying the text display 
tile of a scroll action arg is actually defined, when is described in the chapter 
Advanced Notifier Usage and is usually NOTIFY_SAFE. 

What your tile does with events is largely up to you; however, there are a few 
things to note about certain classes of events. 

□ For LOC_RGNENTER and LOC_RGNEXIT to be generated for tiles, 
LOC_MOVE, LOC_WINENTER and LOC_WINEXIT need to be turned on. 
Remember that tiles share their window’s input mask so they need to 
cooperate in their use of it. 

□ Locator coordinate translation is done so that the event is relative to a tile’s 
coordinate system unless disabled by PW_NO_LOC_AD JUST. 

□ On a WIN_RESIZE event, you can use pw_set_region_rect () to 
change the size and position of your tile’s pixwin region. 

□ On a WIN_REPAINT, you simply repaint your entire tile. The Agent will 
have set the clipping of your pixwin so that only the minimum portion of the 
screen will actually appear to repaint. Alternatively, if you have initially 
told the Agent to maintain a retained image for your tile from which the 
Agent can handle the repainting itself, you will only get a WIN_REPAINT 
call after a window size change. You won’t even get this call if your tile’s 
flags have PW_FIXED_IMAGE and PW_RETAIN bits turned on. 

4.3. Posting Notifications 
Through the Agent 


The Agent follows the lead of the Notifier when it comes to posting events. See 
the documentation on notif y_post_event () and 

not if y_post_event_and_arg () in the Advanced Notifier Usage chapter 
if you are going to be posting events between tiles. 

There are four routines available for posting an event to another tile. 

Notify_error 

win_j?ost_id(client, id, when_hint) 

Notify_client client; 

short id; 

Notify_event_type when_hint; 


The Agent is the conduit by which client-generated events are passed between 
tiles. For example, when the scrollbar wants to tell a canvas that it should now 
scroll, the communications is arranged via the Agent. The Agent, in turn, uses 
the Notifier to implement the data transfer. 
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is provided if you want to send an event to a tile and you don’t really care about 
any event data except the event__id (event). The Agent will generate the 
remainder of the event for you with up-to-date data. when_hint is usually 
NOTIFYJSAFE. 

A second routine is available if you want to manufacture an event yourself. This 
is easy if you already have an event in hand. 

Notify_error 

win_jpost_event (client, event, when_hint) 

Notify_client client; 

Event *event; 

Notify_event_type when_hint; 

The other two routines parallel the first two but include the capability to pass an 
arbitrary additional argument to the destination tile. The calling sequence is 
more complicated because one must make provisions to copy and later free the 
additional argument in case the delivery of the event is delayed. 

Notify__error 

win_j?ost__id_and_arg (client, id, when_hint, arg, 

copy_func, release_func) 

Notify_client client; 

short id; 

Not if y__event_type when__hint ; 

Notify__arg arg; 

Notify_copy copy_func; 

Notify_release release__func; 

Notify_error 

win__post_event_arg (client, event, when__hint, arg, 

copy__func, release_func) 

Notify_client client; 

Event *event; 

Notify_event_type when_hint; 

Notify_arg arg; 

Notify__copy copy_func; 

Notify__release release_func; 

The copy and release functions are covered in the Advanced Notifier Usage 
chapter. After reading about them you will know why you need the following 
utilities to copy the event as well as the arg: 

Notify__arg 

win_copy_event(client, arg, event_ptr) 

Notify_client client; 

Notify_arg arg; 

Event **event_ptr; 


void 

win_free_event(client, arg, event) 
Notify_client client; 
Notify_arg arg; 

Event *event; 
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4.4. Removing a Tile From 
the Agent 


The following call tells the Agent to stop managing the tile associated with 
client. 


int 

win_unregister(client) 

Notify_client client; 

You should call this from the tile’s destroy_f unc that you gave to the Agent 
in the win_register () call. win_unregister () also completely 
removes client from having any conditions registered with the Notifier. A -1 
is returned if client is not registered, otherwise 0 is returned. 
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Windows 


This chapter describes the facilities for creating, positioning, and controlling win¬ 
dows. It contains the implementation details associated with window devices, as 
introduced in the SunView System Model chapter. 

NOTE The recommended window programming approach is described in the SunView 1 
Programmer’s Guide. You should only resort to the following window device 
routines if the equivalent isn’t available at the higher level. It is possible to use 
the following routines with a high level SunView Window object by passing the 
file descriptor returned by 

(int) window_get (Window_object, WIN_FD) ; 

The structure that underlies the operations described in this chapter is maintained 
within the window system, and is accessible to the client only through system 
calls and their procedural envelopes; it will not be described here. The window 
is presented to the client as a device-, it is represented, like other devices, by &jile 
descriptor returned by open(2). It is manipulated by other UNIX system calls, 
such as select(2), read(2), ioctl(2), and close(2). 5 

5.1. Window Creation, As mentioned above, windows are devices. As such, they are special files in the 

Destruction, and /dev directory with names of the form “/dev/win n,” where n is a decimal 

Reference number. A window is created by opening one of these devices, and the window 

name is simply the filename of the opened device. 

A New Window The first process to open a window becomes its owner. A process can obtain a 

window it is guaranteed to own by calling: 

% 

int 

win_getnewwindow() 

This finds the first unopened window, opens it, and returns a file descriptor which 
refers to it. If none can be found, it returns -1. A file descriptor, often called the 
windowfd, is the usual handle for a window within the process that opened it. 

When a process is finished with a window, it may close it with the standard 
close(2) system call with the window’s file descriptor as its argument. As with 
other file descriptors, a window left open when its owning process terminates 

5 The header file <sunwindow/window_hs. h> includes the header files needed to work at this level of 
the window system. The library /usr /1 ib/1 ibsunwindow. a implements window device routines. 
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An Existing Window 


References to Windows 


will be closed automatically by the operating system. 

Another procedure is most appropriately described at this point, although in fact 
clients will have little use for it. To find the next available window, 
win_getnewwindow () uses: 

int 

win_nextfree(fd) 
int fd; 

where f d is any valid window file descriptor. The return value is a window 
number, as described in References to Windows below; a return value of 
WIN_NULLLINK indicates there is no available unopened window. 

It is possible for more than one process to have a window open at the same time; 
the section Providing for Naive Programs below presents one plausible scenario 
for using this capability. The window will remain open until all processes which 
opened it have closed it The coordination required when several processes have 
the same window open is described in Providing for Naive Programs. 

Within the process which created a window, the usual handle on that window is 
the file descriptor returned by open(2) or win_getnewwindow (). Outside 
that process, the file descriptor is not valid; one of two other forms must be used. 
One form is the window name (e.g. /dev/winl2); the other form is the win¬ 
dow number, which corresponds to the numeric component of the window name. 
Both of these references are valid across process boundaries. The window 
number will appear in several contexts below. 

Procedures are supplied for converting among various window identifiers. 
win_numbertoname () stores the filename for the window whose number is 
winnumber into the buffer addressed by name: 

win_numbertoname(winnumber, name) 
int winnumber; 
char *name; 

name should be WIN_NAMESIZE long, as should all the name buffers in this 
section. 

win_name to number () returns the window number of the window whose 
name is passed in name: 

int 

win_nametonumber(name) 
char *name; 

Given a window file descriptor, win_f dtoname () stores the corresponding 
device name into the buffer addressed by name: 

win_fdtoname(windowfd, name) 
int windowfd; 
char *name; 
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win_f dtonumber () returns the window number for the window whose file * 
descriptor is windowf d: 

int 

win_fdtonumber(windowfd) 
int windowfd; 

5.2. Window Geometry 

Once a window has been opened, its size and position may be set. The same rou¬ 
tines used for this purpose are also helpful for adjusting the screen positions of a 
window at other times, when the window is to be moved or stretched, for 
instance. win_setrect () copies the rect argument into the rectangle of the 
indicated window: 

win_setrect(windowfd, rect) 
int windowfd; 

Rect *rect; 

This changes its size and/or position on the screen. The coordinates in the rect 
structure are in the coordinate system of the window’s parent. The Rects and 
Rectlists chapter explains what is meant by a rect. Setting Window Links 
below explains what is meant by a window’s “parent.” Changing the size of a 
window that is visible on the screen or changing the window’s position so that 
more of the window is now exposed causes a chain of events which redraws the 
window. See the section entitled Damage in the Advanced Imaging chapter. 

Querying Dimensions 

The window size querying procedures are: 

win__getrect (windowfd, rect) 
int windowfd; 

Rect *rect; 

win__getsize (windowfd, rect) 
int windowfd; 

Rect *rect; 

short win_getheight(windowfd) 
int windowfd; 

short win_getwidth(windowfd) 
int windowfd; 

w i n _J?etrect () stores the rectangle of the window whose file descriptor is 
windowfd into the rect; the origin is relative to that window’s parent. 

win_getsize () is similar, but the rectangle is self-relative — that is, the ori¬ 
gin is (0,0). 

w i n _getheight () and win_getwidth () return the single requested 
dimension for the indicated window — these are part of the rect structure that 
the other calls return. 
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The Saved Rect 


5.3. The Window 
Hierarchy 


Setting Window Links 


A window may have an alternate size and location; this facility is useful for stor¬ 
ing a window’s iconic position that is associated with frames. The alternate rec¬ 
tangle may be read with win_get savedrect (), and written with 
win_setsavedrect(). 

win_getsavedrect(windowfd, rect) 
int windowfd; 

Rect *rect; 

win_setsavedrect(windowfd, rect) 
int windowfd; 

Rect *rect; 

As with win_getrect () and win_setrect (), the coordinates are relative 
to the screen. 

Position in the window database determines the nesting relationships of win¬ 
dows, and therefore their overlapping and obscuring relationships. Once a win¬ 
dow has been opened and its size set, the next step in creating a window is to 
define its relationship to the other windows in the system. This is done by setting 
links to its neighbors, and inserting it into the window database. 

The window database is a strict hierarchy. Every window (except the root) has a 
parent; it also has 0 or more siblings and children. In the terminology of a family 
tree, age corresponds to depth in the layering of windows on the screen: parents 
underlie their offspring, and older windows underlie younger siblings which 
intersect them on the display. Parents also enclose their children, which means 
that any portion of a child’s image that is not within its parent’s rectangle is 
clipped. Depth determines overlapping behavior: the uppermost image for any 
point on the screen is the one that gets displayed. Every window has links to its 
parent, its older and younger siblings, and to its oldest and youngest children. 

Windows may exist outside the structure which is being displayed on a screen; 
they are in this state as they are being set up, for instance. 

The links from a window to its neighbors are identified by link selectors-, the 
value of a link is a window number. An appropriate analogy is to consider the 
link selector as an array index, and the associated window number as the value 
of the indexed element. To accommodate different viewpoints on the structure 
there are two sets of equivalent selectors defined for the links: 

WL_PARENT == WL_ENCLOSING 

WL_OLDERSIB == WL_COVERED 

WL_YOUNGERSIB == WL_COVERING 

WL_OLDESTCHILD == WL_BOTTOMCHILD 

WL_YOUNGE S TCHILD == WL_TOPCHILD 

A link which has no corresponding window, for example, a child link of a “leaf’ 
window, has the value WIN_NULLLINK. 

When a window is first created, all its links are null. Before it can be used for 
anything, at least the parent link must be set so that other routines know with 
which desktop and workstation this window is to be associated. If the window is 
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Activating the Window 


Defaults 


to be attached to any siblings, those links should be set in the window as well. 
The individual links of a window may be inspected and changed by the following 
procedures. 

win__getlink () returns a window number, 
int 

win_getlink(windowfd, link_selector) 
int windowfd, link_selector; 

This number is the value of the selected link for the window associated with 
windowfd. 

win_setlink(windowfd, link_selector, value) 
int windowfd, link_selector, value; 

w i n _setlink () sets the selected link in the indicated window to be value, 
which should be another window number or WIN_NULLLINK. The actual win¬ 
dow number to be supplied may come from one of several sources. If the win¬ 
dow is one of a related group, all created in the same process, file descriptors will 
be available for the other windows. Their window numbers may be derived from 
the file descriptors via win_f dt onumber (). The window number for the 
parent of a new window or group of windows is not immediately obvious, how¬ 
ever. The solution is a convention that the WINDOW_PARENT environment 
parameter will be set to the filename of the parent. See 
we_setparent window () for a description of this parameter. 

Once a window’s links have all been defined, the window is inserted into the tree 
of windows and attached to its neighbors by a call to 

win_insert(windowfd) 
int windowfd; 

This call causes the window to be inserted into the tree, and all its neighbors to 
be modified to point to it. This is the point at which the window becomes avail¬ 
able for display on the screen. 

Every window should be inserted after its rectangle(s) and link structure have 
been set, but the insertion need not be immediate: if a subtree of windows is 
being defined, it is appropriate to create the window at the root of this subtree, 
create and insert all of its descendants, and then, when the subtree is fully 
defined, insert its root window. This activates the whole subtree in a single 
action, which may result in cleaner display of the whole tree. 

One need not specify all the sibling links of a window that is being inserted into 
the display tree. Sibling links may be defaulted as follows (these conventions are 
applied in order): 

□ If the WL_COVERING sibling link is WIN_NULLLINK then the window is 
put on the top of the heap of windows. 
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Modifying Window 
Relationships 


□ If the WL_COVERED sibling link is WIN_NULLLINK then the window is 
put on the bottom of the heap of windows. 

□ If the WL_COVERED or WL_COVERING sibling links are invalid then the 
window is put on the bottom of the heap of windows. 

Once a window has been inserted in the window database, it is available for input 
and output. At this point, it is appropriate to access the screen with pixwin calls 
(to draw something in the window!). 

Windows may be rearranged in the tree. This will change their overlapping rela¬ 
tionships. For instance, to bring a window to the top of the heap, it should be 
moved to the “youngest” position among its siblings. And to guarantee that it is 
at the top of the display heap, each of its ancestors must likewise be the youngest 
child of its parent. 

To accomplish such a modification, the window should first be removed: 

win_remove(windowfd) 
int windowfd; 

After the window has been removed from the tree, it is safe to modify its links, 
and then reinsert it. 

A process doing multiple window tree modifications should lock the window tree 
before it begins. This prevents any other process from performing a conflicting 
modification. This is done with a call to: 

win_lockdata(windowfd) 
int windowfd; 

After all the modifications have been made and the windows reinserted, the lock 
is released with a call to: 

win_unlockdata(windowfd) 
int windowfd; 

Nested pairs of calls to lock and unlock the window tree are permitted. The final 
unlock call actually releases the lock. 

If a client program uses any of the window manager routines, use of 
win_lockdata () and win_unlockdata () is not necessary. See the 
chapter on Window Management for more details. 

Most routines described in this chapter, including the four above, will block tem¬ 
porarily if another process either has the database locked, or is writing to the 
screen, and the window adjustment has the possibility of conflicting with the 
window that is being written. 

As a method of deadlock resolution, SIGXCPU is sent to a process that spends 
more that 2 seconds of process virtual time inside a window data lock, and the 
lock is broken. 6 


6 The section Kernel Tuning Options in the Workstation chapter describes how to modify this default 
number of seconds (see ws_lock_limit). 



Revision A, of May 9,1988 











Chapter 5 — Windows 35 


Window Enumeration There are routines that pass a client-defined procedure to a subset of the tree of 

windows, and another that returns information about an entire layer of the win¬ 
dow tree. They are useful in performing window management operations on 
groups of windows. The routines and the structures they use and return are listed 
in <sunwindow/win_enum.h>. 

Enumerating Window Offspring The routines win_enumerate_children () and 

win_enumerate_subtree () repeatedly call the client’s procedure passing 
it the windowfds of the offspring of the client window, one after another: 

enum win__enumerator_resuit 

win__enumerate_children (windowfd, proc, args) ; 

Window__handle windowfd; 

Enumerator proc; 
c a ddr_t args; 

enum win_enumerator_result 

win_enumerate_subtree(windowfd, proc, args); 

Window_handle windowfd; 

Enumerator proc; 
caddr__t args; 

enum win__enumerator_result \ 

{ Enum_Norma 1, Enum__Succeed, Enum_Fail }; 

typedef enum win_enumerator_result 
(^Enumerator)(); 

windowfd is the window whose children are enumerated (Window_handle is 
typedef ’d to int). Both routines repeatedly call proc (), stopping when 
told to by proc () or when everything has been enumerated. 

proc () is passed a windowfd and args 

(*proc)(fd, args); 

It does whatever it wants with the windowfd, then returns 
win_enumerator_result. If proc () returns Enum_Norma 1 then the 
enumeration continues; if it returns Enum_Succeed or Enum_Fail then the 
enumeration halts, and win_enumerate_children or 
w in_enumerate_subtree () returns the same result. 

The difference between the two enumeration procedures is that 
win _enumerate_children () invokes proc ( ) with an fd for each 
immediate descendant of windowfd in oldest-to-youngest order, while 
win_enumerate_subtree ( ) invokes proc () with a windowfd for the 
original window windowfd and for all of its descendants in depth-first, oldest- 
to-youngest order. The former enumerates windowf d’s children, the latter 
enumerates windowfd and its extended family. 

It is possible that win_enumerate_subtree () can run out of file descrip¬ 
tors during its search of the tree if the descendants of windowfd are deeply 
nested. 
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Fast Enumeration of the 
Window Tree 


5.4. Pixwin Creation and 
Destruction 


Creation 


The disadvantage with the above two routines is that they are quite slow. They 
traverse the window tree, calling win_get link () to find the offspring, then 
open each window, then call the procedure. 

In 3.2 there is a fast window routine, win_get_tree_layer (), that returns 
information about all the children of a window in a single ioctl^: 

win_get_tree_layer(parent, size, buffer); 

Window_handle parent; 
u_int size; 

char *buffer; 

typedef struct win_enum_node { 
unsigned char me; 
unsigned char parent; 
unsigned char upper_sib; 
unsigned char lowest_kid; 
unsigned int flags; 

#define WIN_NODE_INSERTED Oxl 

#define WIN_NODE_OPEN 0X2 

♦define WIN_NODE_IS_ROOT 0x4 

Rect open_rect; 

Rect icon_rect; 

) Win_enum_node; 

win_get_tree_layer () fills buffer with Win_enum_node informa¬ 
tion (rects, user flags, and minimal links) for the children of window in oldest- 
to-youngest order. It returns the number of bytes of buff er filled with infor¬ 
mation, or negative if there is an error. 

Unlike win_enumerate_children (), win_get_tree_layer () 
returns information for all the children of windowf d including those that are 
have not been installed in the window tree with win_insert () ; such children 
will not have the WlN_NODE_INSERTED flag set. 

A pixwin is the object that you use to access the screen. Its usage has been 
covered in the Imaging Facilities: Pixwins chapter of the SunView Programmer’s 
Guide and in the previous chapter on tiles. How to create a pixwin region has 
also been covered in the same places. Here we cover how a pixwin is generated 
for a window. 

To create a pixwin, the window to which it will refer must already exist. This 
task is accomplished with procedures described earlier in this chapter. The 
pixwin is then created for that window by a call to pw_open (): 

Pixwin * 

pw_open(windowfd) 
int windowfd; 

pw_open () takes a file descriptor for the window on which the pixwin is to 

7 win_get_t ree layer ( ) will use the slower method if the kernel does not support the ioctl; thus 
programs that use this can be run on 3.0 systems. 
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Region 


Retained Image 


Bell 


Destruction 


5.5. Choosing Input 


Input Mask 


write. A pointer to a pixwin struct is returned. At this point the pixwin describes 
the exposed area of the window. 

To create the pixwin for a tile, call pw_region () passing it the pixwin 
returned from pw_open (). 

If the client wants a retained pixwin, the pw_jprretained field of the pixwin 
should be set to point to a memory pixrect of your own creation. If you set this 
field you need to call pw_exposed (pw) afterwards. 8 This updates the 
pixwin’s exposed area list to deal with the memory pixrect; see the Advanced 
Imaging chapter for more information on pw_expose (). 

The following routine can be used to beep the keyboard bell and flash a pixwin: 

win_bell(windowfd, wait_tv, pw) 
int windowfd; 
struct timeval wait_tv; 

Pixwin *pw; 

If pw is 0 then there is no flash. wait_t v controls the duration of the bell. 9 

When a client is finished with a pixwin, it should be released by a call to: 

pw__close (pw) 

Pixwin *pw; 

pw_close () frees any resource associated with the pixwin, including its 
pw_prretained pixrect if any. If the pixwin has a lock on the screen, it is 
released. 

The chapter entitled Handling Input in the SunView Programmer*s Guide 
describes the window input mechanism. This section describes the file descriptor 
level interface to setting a window’s input masks. This section is very terse, 
assuming that the concept from Handling Input are well understood. 

Clients specify which input events they are prepared to process by setting the 
input masks for each window being read. The calls in this section manipulate 
input masks. 


8 The best way to manage a retained window is to let the Agent do it (see win register ()). 

9 The bell’s behavior is controlled by the SunView de fault sedit entries SunView!Audible Bell and 
Sunview/Visible_Bell y so the sound and flash can be disabled by the user, regardless of what the call to 
win_bell() specifies. 
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Manipulating the Mask 
Contents 


Setting a Mask 


typedef struct inputmask { 
short im__flags; 


#define 

IM_ 

NEGEVENT 

(0x01) 

/* 

#define 

IM_ 

[ascii 

(0x10) 

/* 

#define 

IM_ 

[meta 

(0x20) 

/* 

#define 

IM_ 

_NEGASCII 

(0x40) 

/* 

#define 

IM_ 

_NEGMETA 

(0x80) 

/* 

#define 

IM_ 

_INTRANSIT 

(0x400) 

/* 


} Inputmask; 


send input negative events too */ 
enable ASCII codes 0-127 */ 
enable META codes 128-255 */ 
enable negative ASCII codes 0-127 */ 
enable negative META codes 128-255 *, 
don't surpress locator events when 
in-transit over window */ 


The bit flags defined for the input mask are stored directly in the im_f lags 
field. To set a particular event in the input mask use the following macro: 


win_setinputcodebit(im, code) 

Inputmask *im; 
u_short code; 

win_setinputcodebit () sets a bit indexed by code in the input mask 
addressed by im to 1. 


win__unsetinputcodebit (im, code) 

Inputmask *im; 
u_short code; 

win_unsetinputcodebit () resets the bit to zero. 

The following macro is used to query the state of an event code in an input mask: 


int 

win_getinputcodebit(im, code) 

Inputmask *im; 
u_short code; 

win_getinputcodebit () returns non-zero if the bit indexed by code in 
the input mask addressed by im is set. 

input_imnull () initializes an input mask to all zeros: 

input__imnull (im) 

Inputmask *im; 

It is critical to initialize the input mask explicitly when the mask is defined as a 
local procedure variable. 

The following routines set the keyboard and pick input masks for a window. The 
different types of masks are discussed in the Input chapter. 

win_set_kbd_mask(windowfd, im) 
int windowfd; 

Inputmask *im; 


win_set_pick_mask(windowfd, 
int windowfd; 

Inputmask *im; 


im) 
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Querying a Mask 


The Designee 


5.6. Reading Input 


Non-blocking Input 


Asynchronous Input 


The following routines get the keyboard and pick input masks for a window. 

win_get__kbd_mask (windowfd, im) 
int windowfd; 

Inputmask *im; 

win_get_pick_mask(windowfd, im) 
int windowfd; 

Inputmask *im; 


The designee is that window that input is directed to if the input mask for a win¬ 
dow doesn’t match a particular event: 

win_get_designee(windowfd, nextwindownumber) 
int windowfd, *nextwindownumber; 

win_set__designee (windowfd, nextwindownumber) 
int windowfd, nextwindownumber; 


The recommended way of getting input is to let the Agent notify you of input 
events (see chapter on tiles). However, there are times when you may want to 
read input directly, say, when tracking the mouse until one of its buttons goes up. 
A library routine exists for reading the next input event for a window: 

int 

input_readevent(windowfd, event) 
int windowfd; 

Event *event; 

This fills in the event struct, and returns 0 if all went well. In case of error, it 
sets the global variable errno, and returns -1; the client should check for this 
case. 

A window can be set to do either blocking or non-blocking reads via a standard 
f cntl(2) system call, as described in f cntl(2) (using _SETFL) and 
fcntl(5) (using FNDELAY). A window defaults to blocking reads. The block¬ 
ing status of a window can be determined by the f cntl(2) system call. 

When all events have been read and the window is doing non-blocking I/O, 
i nput_readevent () returns -1 and the global variable errno is set to 
EWOULDBLOCK. 

A window process can ask to be sent a SIGIO if any input is pending in a win¬ 
dow. This option is also enabled via a standard f cntl(2) system call, as 
described in f cntl(2) (using F_SETFL) and f cntl(5) (using FASYNC). The 
programmer can set up a signal handler for SIGIO by using the 
notify_set_signal_func () call. 10 


10 The Notifier handles asynchronous input without you having to set up your own signal handler if you are 
using the Notifier to determine when there is input for a window. 
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Events Pending 


5.7. User Data 


5.8. Mouse Position 


The number of character in the input queue of a window can be determined via a 
FBIONREAD ioctl(2) call. FBIONREAD is described in tty(4). Note that 
the value returned is the number of bytes in the input queue. If you want the 
number of Events then divide by sizeof (Event). 

Each window has 32 bits of data associated with it. These bits are used to imple¬ 
ment a minim al inter-process window-related status-sharing facility. Bits 0x01 
through 0x08 are reserved for the basic window system; 0x01 is currently used to 
indicate if a window is a blanket window. Bits 0x10 through 0x80 are reserved 
for the user level window manager; 0x10 is currently used to indicate if a win¬ 
dow is iconic. Bits 0x100 through 0x80000000 are available for the 
programmer’s use. They is manipulated with the following procedures: 

int 

win_getuserflags(windowfd) 
int windowfd; 

int 

win_setuserflags(windowfd, flags) 
int windowfd; 
int flags; 

int 

win_setuserflag(windowfd, flag, value) 
int windowfd; 
int flag; 
int value; 

win_getuserflags () returns the user data. win_setuserflags () 
stores its flags argument into the window struct. win_setuserf lag () 
uses flag as a mask to select one or more flags in the data word, and sets the 
selected flags on or off as value is TRUE or FALSE. 

Determining the mouse’s current position is treated in the SunView 
Programmer’s Guide. The convention for a process tracking the mouse is to 
arrange to receive an input event every time the mouse moves; the mouse posi¬ 
tion is passed with every user input event a window receives. 

The mouse position can be reset under program control; that is, the cursor can be 
moved on the screen, and the position that is given for the mouse in input events 
can be reset without the mouse being physically moved on the table top. 

win_setmouseposition(windowfd, x, y) 
int windowfd, x, y; 

win_setmouseposition () puts the mouse position at (x, y) in the coordi¬ 
nate system of the window indicated by windowfd. The result is a jump from 
the previous position to the new one without touching any points between. Input 
events occasioned by the move, such as window entry and exit and cursor 
changes, will be generated. This facility should be used with restraint, as many 
users are unhappy with a cursor that moves independent of their control. 

Occasionally it is necessary to discover which window underlies the cursor, usu¬ 
ally because a window is handling input for all its children. The procedure used 
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for this purpose is: 
int 

win_findintersect(windowfd, x, y) 
int windowfd, x, y; 

where windowfd is the calling window’s file descriptor, and (x, y) defines a 
screen position in that window’s coordinate space. The returned value is a win¬ 
dow number of a child of the calling window. If a child of the calling window 
doesn’t fall under the given position WIN_NULLLINK is returned. 

5.9. Providing for Naive There is a class of applications that are relatively unsophisticated about the win- 

Programs dow system, but want to run in windows anyway. For example, a graphics pro¬ 

gram may want a window in which to ran, but doesn’t want to know about all the 
details of creating and positioning it. This section describes a way of allowing 
for these applications. 

Which Window to Use The window system defines an important environment parameter, 

WlNDOW_GFX. By convention, WINDOW_GFX is set to a string that is the dev¬ 
ice name of a window in which graphics programs should be run. This window 
should already be opened and installed in the window tree. Routines exist to 
read and write this parameter: 

int 

we_getgfxwindow(name) 
char *name 

we_setgfxwindow(name) 
char *name 

we_getgf xwindow () returns a non-zero value if it cannot find a value. 

The Blanket Window A good way to take over an existing window is to create a new window that 

becomes attached to and covers the existing window. Such a covering window is 
called a blanket window. The covered window will be called the parent window 
in this subsection because of its window tree relationship with a blanket win¬ 
dow. 11 

The appropriate way to make use of the blanket window facility is as follows: 
Using the parent window name from the environment parameter WINDOW_GFX 
(described above), open(2) the parent window. Get a new window to be used as 
the blanket window using win_getnewwindow (). Now call: 

int 

win_insertblanket(blanketfd, parentfd) 
int blanketfd, parentfd; 

A zero return value indicates success. As the parent window changes size and 
position the blanket window will automatically cover the parent. 


11 It’s a bad idea to take over an existing window using win set owner (). 
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To remove the blanket window from on top of the parent window call: 

win_removeblanket(blanketfd) 
int blanketfd; 

If the process that owns the window over which the blanket window resides dies 
before win_removeblanket () is called, the blanket window will automati¬ 
cally be removed and destroyed. 

A non-zero return value from win_isblanket () indicates that blanketfd 
is indeed a blanket window. 

int 

win_isblanket(blanketfd) 
int blanketfd; 


5.10. Window Ownership SIGWINCH signals are directed to the process that owns the window, the owner 

normally being the process that created the window. The following procedures 
read from and write to the window: 12 These routines are included for backwards 
compatibility. 

int 

win_getowner(windowfd) 
int windowfd; 

win_setowner(windowfd, pid) 
int windowfd, pid; 

win_getowner () returns the process id of the indicated window owner. If 
the owner doesn’t exist, zero is returned. win_setowner () makes the process 
identified by pid the owner of the window indicated by windowfd. 
win_setowner causes a SIGWINCH to be sent to the new owner. 

5.11. Environment Environment parameters are used to pass well-established values to an applica- 

Parameters tion. They have the valuable property that they can communicate information 

across several layers of processes, not all of which have to be involved. 

Every frame must be given the name of its parent window. A frame’s parent 
window is the window in the display tree under which the frame window should 
be displayed. The environment parameter WlNDOW_PARENT is set to a string 
that is the device name of the parent window. For a frame, this will usually be 
the name of the root window of the window system. 

we_setparentwindow(windevname) 
char *windevname; 

sets WINDOW PARENT to windevname. 


12 Do not use the two routines in this section for temporarily talcing over another window. 
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int 

we_getparentwindow(windevname) 
char *windevname; 

gets the value of WINDOW_PARENT into windevname. The length of this 
string should be at least WIN_NAMESIZE characters long, a constant found in 
<sunwindow/win_struct . h>. A non-zero return value means that the 
WINDOW_PARENT parameter couldn’t be found. 

The environment parameter DEFAULT_FONT should contain the font file name 
used as the program’s default (see pf_def ault ()). 

NOTE This is retained for backwards compatibility. All programs set this variable , but 

only old-style SunWindows programs , gfx subwindow programs and raw pixwin 
programs use it to determine which font to use. SunView programs that don t set 
their own font use the SunView/Font defaults entry; you can use the -Wt 
fontname command line frame argument to change the font of SunView programs 
that allow it. 

5.12. Error Handling Except as explicitly noted, the procedures described in this section do not return 

error codes. The standard error reporting mechanism inside the sunwindow 
library is to call an error handling routine that displays a message, typically iden¬ 
tifying the ioct 1(2) call that detected the error. This error message is some¬ 
what cryptic; Appendix B, Programming Notes , has a section on Error Message 
Decoding . After the message display, the calling process resumes execution. 

This default error handling routine may be replaced by calling: 

int (*win_errorhandler(win_error))() 
int (*win_error)(); 

The win_errorhandler () procedure takes the address of one procedure, the 
new error handler, as an argument and returns the address of another procedure, 
the old error handler, as a result. Any error handler procedure should be a func¬ 
tion that returns an integer. 

win_error(errnum, winopnum) 
int errnum, winopnum; 

errnum will be -1 indicating that the actual error number is found in the global 
err no. winopnum is the ioct 1(2) number that defines the window operation 
that generated the error. See Section B.4, Error Message Decoding , in Appendix 
B, Programming Notes. 
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Desktops 


This chapter discusses the calls that affect the screen, or desktop. Some calls 
affect workstation-related data, i.e., global input related data. This overlap of the 
conceptual model is purely historical. 

Look at sunview Many of the routines in here are used by Sun’s window manager, sunview(l). 

You will find it very helpful to look at the source for sunview (it is optional 
software that must be loaded in suninstall) to see how it uses these routines. 

6.1. Multiple Screens Workstations may use multiple displays, and clients may want windows on all of 

them. 13 Therefore, the window database is a forest, with one tree of windows for 
each display. There is no overlapping of window trees that belong to different 
screens. For displays that share the same mouse device, the physical arrange¬ 
ment of the displays can be passed to the window system, and the mouse cursor 
will pass from one screen to the next as though they were continuous. 

The singlecolor Structure The screen structure describes attributes of the display screen. First, here is 

the definition of singlecolor, which it uses for the foreground and back¬ 
ground colors: 

struct singlecolor { 

u_char red, green, blue; 

1; 


There can be as many screens as there are frame buffers on your machine and dlop pseudo devices 
configured into your kernel. The kernel calls screen instances dtops. 
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The screen Structure 


Screen Creation 


Now the screen structure: 


struct screen 

{ 

char 

scr rootname [SCR__NAMESIZE] ; 

char 

scrjcbdname [SCR_NAMESIZE] ; 

char 

scr msname[SCR_NAMESIZE]; 

char 

scr fbname[SCR_NAMESIZE]; 

struct 

singlecolor scr_foreground; 

struct 

singlcolor scr_background; 

int 

scr_flags; 

struct 

}; 

rect scr__rect; 


♦define SCR_NAMESIZE 20 
♦define SCR_SWITCHBKGRDFRGRD 0x1 

scr_rootname is the device name of the window which is at the base of the 
window display tree for the screen; it is often /dev/winO , 14 scr_kbdname is 
the device name of the keyboard associated with the screen; the default is 
/dev/kbd. scr_msname is the device name of the mouse associated with the 
screen; the default is /dev/mouse. scr_fbname is the device name of the 
frame buffer on which the screen is displayed; the default is / dev/ f b for the 
first desktop. scr_kbdname, scr_msname and scr_fbname can have the 
string “NONE” if no device of the corresponding type is to be associated with the 
screen. Workstations (hence also desktops) can have additional input devices 
associated with them; see the section on User Input Device Control in the Works¬ 
tations chapter. 

scr_f oreground is three RGB color values that define the foreground color 
used on the frame buffer; the default is { colormap size-1, colormap size-1, 
colormap size-1 }. scr_background is three RGB color values that define 
the background color used on the frame buffer; the default is {0, 0, 0}. The 
default values of the background and foreground yield a black on white image, 
serf lags contains boolean flags; the default is 0. 

SCR_SWITCHBKGRDFRGRD is a flag that directs any client of the background 
and foreground data to switch their positions, thus providing a video reversed 
image (usually yielding a white on black image). scr_rect is the size and 
position of the screen on the frame buffer; the default is the entire frame buffer 
surface. 

To create a new screen call: 
int 

win_screennew(screen) 

struct screen ‘screen; 


14 Multiple screen configurations, in particular, will not have /dev/winO as the root window on the second 
screen. 
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Initializing the screen 
Structure 


Screen Query 


Screen Destruction 


Screen Position 


win__screennew ( ) opens and returns a window file descriptor for a root 
desktop window. This new root window resides on the new screen which was 
defined by the specifications of screen. Any zeroed field in screen tells 
win_screennew () to use the default value for that field (see above for 

defaults). Also, see the description of win_initscreenf romargv () 

below. If—1 is returned, an error message is displayed to indicate that there was 
some problem creating the screen. 

The following routine can be called before calling win_screennew (): 
int 

win_initscreenfromargv(screen, argv) 
struct screen ‘screen; 
char **argv; 

win_initscreenf romargv () zeroes the ‘screen structure, then it parses 
the relevant command line arguments in argv into * screen. You then call 
win_screennew () to creates a root window with the desired attributes. The 
command line arguments allow the user to set all the variables in ‘screen 
including the display device, the keyboard device, the mouse device, the fore¬ 
ground and background colors, whether the screen colors should be inverted, and 
other features. See sunview(l) for semantics and details. 

To find out about the screen on which your window is running call: 

win_screenget(windowfd, screen) 
int windowfd; 

struct screen ‘screen; 

w i n __screenget () fills in the addressed struct ‘screen with information 
for the screen with which the window indicated by windowfd is associated. 

You can call this from any window. 

To destroy the screen on which your window is running call: 

win_screendestroy(windowfd) 
int windowfd; 

w i n _screendestroy () causes each window owner process (except the 
invoking process) on the screen associated with windowfd to be sent a 
SIGTERM signal. This call will block until all the processes have died. If a win¬ 
dow owner process hasn’t gone away after 15 seconds, it is sent a SIGKILL, 
which will destroy it. 

To tell the window system how multiple screens are arranged call: 
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win setscreenpositions(windowfd, neighbors) 
int windowfd, neighbors[SCR_POSITIONS]; 

#define SCR_NORTH 0 
tdefine SCRJEAST 1 
#define SCR_SOUTH 2 
#define SCR_WEST 3 

#define SCR_POSITIONS 4 

win__set screenpositions () informs the window system of the logical 
layout of multiple screens. This enables the cursor to cross to the appropriate 
screen, windowf d’s window is the root for its screen; the four slots in neigh¬ 
bors should be filled in with the window numbers of the root windows for the 
screens in the corresponding positions. No diagonal neighbors are defined, since 
they are not strictly neighbors. 


win__getscreenpositions () fills in neighbors with windowf d’s 
screen’s neighbors: 

win_getscreenpositions(windowfd, neighbors) 
int windowfd, neighbors[SCR_POSITIONS]; 

CAUTION In these routines, windowfd must be an fd for the root window. Most 
operations on the screen can be done using any windowfd. 

Accessing the Root FD The following code fragment gets the screen struct for your window, then 

opens the window device of the root window: 

-—-—-\ 

int mywinfd, rootfd; 
struct screen rootscreen; 

win__screenget (mywinfd, &rootscreen) ; 
rootfd = open(rootscreen.scr_rootname); 
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Workstations 


This chapter discusses the manipulation of workstation data, which comprises 
mostly global data related to input and input devices. Some calls in the Desktops 
chapter also affect workstations. This overlap is purely historical. This chapter 
also explains parts of the Virtual User Input Device interface that were not 
covered in the Handling Input chapter of the SunView 1 Programmer’s Guide. 
That chapter gave the possible event codes in SunView 1; this chapter explains 
the mechanism which sets up input devices to generate them. 

7.1. Virtual User Input The Virtual User Input Device ( vuid) is an interface between input devices and 

Device their clients. The interface defines an idealized user input device that may not 

correspond to any existing physical collection of input devices. A client of Sun¬ 
View doesn’t access vuid devices directly. Instead, the window system reads 
vuid devices, serializing input from all the vuid devices and then makes the input 
available to windows as SunView vuid events. 

NOTE You don’t have to write a vuid interface to use your own device in SunView: you 
can use any input device that generates ASCII. But if your device is hooked up 
using vuid, then your SunView programs can interface with it using the SunView 
input event mechanism. 

Since SunView’s input system is built on top of vuid, it is explained in some 
detail. 

What Kind of Devices? Vuid is targeted to input devices that gather command data from humans, e.g., 

mice, keyboards, tablets, joysticks, light pens, knobs, sliders, buttons, ascii termi¬ 
nals, etc. 15 The vuid interface is not designed to support input devices that pro¬ 
duce voluminous amounts of data, such as input scanners, disk drives, voice 
packets. 

Here are some of the properties that are expected of a typical client of vuid, e.g., 
SunView: 

□ The client has a richer user interface than can be supported by a simple 
ASCII terminal. 


15 The appendix titled Writing a Virtual User Input Device Driver discusses how to write a device driver 
that speaks the vuid protocol for a new input device. 
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Vuid Features 


Vuid Station Codes 


Address Space Layout 


□ The client serializes multiple input devices being used by the user into a sin¬ 
gle stream of events. 

□ The client preserves the entire state of its input so that it may query this 
state. 

Vuid provides, among others, the following services to clients: 

□ A client may extend the capabilities of the predefined vuid by adding input 
devices. A client wants to be able to do this in a way that fits smoothly with 
its existing input paradigm. 

□ A client’s code may be input device independent. A client can replace the 
physical device(s) underlying the virtual user input device and not have to 
change any input or event handlers, only the input device driver. In fact, the 
vuid interface doesn’t care about physical devices. One physical device can 
masquerade as many logical devices and many physical devices can look 
like a single logical device. 

This section defines the layout of the address space of vuid station codes. It 
explains how to extend the vuid address space for your own purposes. The 
meaning of vuid station codes is covered in the Handling Input chapter of the 
SunView 1 Programmer’s Guide. The programmatic details of the vuid interface 
are covered in Writing a Virtual User Input Device Driver appendix to this docu¬ 
ment, 

The address space for vuid events is 16 bits long, from 0 to 65535 inclusive. It is 
broken into 256 segments that are 256 entries long (VUID_SEG_SIZE). The 
top 8 bits contain a vuid segment identifier value. The bottom 8 bits contain a 
segment specific value from 0 to 255. Some segments have been predefine and 
some are available for expansion. Here is how the address space is currently bro¬ 
ken down: 

□ ASCII_DEVID (0x00) — ASCII codes, which include META codes. 

□ TOP_DEVID (0x01) — Top codes, which are ASCII with the 9th bit on. 
o Reserved (0x02 to 0x7B) — for Sun vuid implementations. 

□ SUNVIEW_DEVID (0x7C) — SunView semantic “action” events generated 
inside SunView by keymapping. 

□ P ANEL_DEVID (0x7D) — Panel subwindow package event codes used 
internally in the panel package (see <suntool/panel. h>). 

o SCROLL_DEVlD (0x7E) — Scrollbar package event codes passed to 
scrollbar clients on interesting scrollbar activity (see 
<suntool/scrollbar. h>). 
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This device is a bit of a hodge¬ 
podge for historical reasons; the 
middle of the address space has 
SunView-related events in it (see 
<sunwindow/win_input. h>), 
and the virtual keyboard and virtual 
locator are thrown together. 

Adding a New Segment 


NOTE 


Input State Access 


Unencoded Input 


□ WORKSTATION_DEVID (0x7F) — Virtual keyboard and locator (mouse) 
related event codes that describe a basic "workstation" device collection (see 
<sundev/vuid_event .h>). 

□ Reserved for Sun customers (0x80 to OxFF) — if you are writing a new vuid, 
you can use a segment in here; see the next section. 

<sundev/vuid_event. h> is the central registry of virtual user input dev¬ 
ices. To allocate a new vuid you must modify this file: 

□ Choose an unused portion of the address space. Vuids from 0x00 to 0x7F 
are reserved for use by Sun. Vuids from 0x80 to OxFF are reserved for Sun 
customers. 

□ Add the new device with a *_DEVID #def ine in this file. Briefly 
describe the purpose/usage of the device. Mention the place where more 
information can be found. 

□ Add the new device to the Vuid_device enumeration with a 
VUID _devname entry. 

o List the specific event codes in another header file that is specific to the new 
device. ASCII_DEVID, TOP_DEVID and WORKSTATION_DEVID events 
are listed in <sundev/vuid_event. h> for historical reasons. 

A new vuid device can just as easily be a pure software construction as it can be 
a set of unique codes emitted by a new physical device driver. 

The complete state of the virtual input device is available. For example, one can 
ask questions about the up/down state of arbitrary keys. 

int 

win_get_vuid_value(windowfd, id) 
int windowfd; 
short id; 

id is one of the event codes from <sundev/vuid event . h> or 
<sunwindow/win_input . h>. windowfd can be any window file descrip¬ 
tor. 

The result returned for keys is 0 for key is up and 1 for key is down; some vuid 
events return a range of numbers, such as mouse position. There is no error code 
for “no such key” because, by definition, the vuid event address space is the 
entire range of shorts and therefore you can’t ask an incorrect question. 0 is 
the default event state. 

Unencoded keyboard input is supported, for those customers who cannot use the 
normal keyboard input mechanism . 


A new keyboard translation was introduced in 3.2. The type of translation is set 
by the KIOCTRANS ioctl (see kb(4S) and kbd(4S)). Old values were: 


This device is a bit of a hodge¬ 
podge for historical reasons; the 
middle of the address space has 
SunView-related events in it (see 
<sunwindow/win_input. h>), 
and the virtual keyboard and virtual 
locator are thrown together. 

Adding a New Segment 


NOTE 


Input State Access 


Unencoded Input 
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TR_NONE 
TR_ASCII 
TR EVENT 


for unencoded keyboard input outside the window sys¬ 
tem 

for ASCII events (characters and escape sequences) out¬ 
side the window system 

for window input events inside the window system 


A new value is now supported: 


TR_UNTRANS_EVENT 

gives unencoded keyboard values for input events inside the win¬ 
dow system. 

The client must have WIN_ASCII_EVENTS set in the window’s input mask; if 
up-transitions are desired, WIN_UP_ASCII_EVENTS must also be set. (See 
Chapter 6, Handling Input, in the SunView Programmer’s Guide for how to set 
input masks.) 

The number of the key pressed or released will be passed in the event’s id 
ie_code, and the direction of the transition will be reported correctly by 
event_is_up () and event__is_down () (i.e., the NEGEVENT flag in 
ie_f lags will be correct). The state of the shiftmask is undefined. 

Events for other input (e.g. from the mouse) will be merged in the same stream 
with keyboard input, in standard window input fashion. 

NOTE Setting the keyboard translation has a global effect—it is not possible to get 
encoded input in one window and unencoded input in another on the same 
workstation. 


7.2. User Input Device 
Control 


The number and kind of physical user input devices that can be used to drive 
SunView is open ended. Here are the controls for manipulating those devices. 


Distinguished Devices 


A keyboard and a mouse-like device are distinguished and settable directly. The 
Desktops chapter describes how they are specified in the screen structure. 

Here are two calls for changing them explicitly. 

int 

win_setkbd(windowfd, screen) 
int windowfd; 

struct screen *screen; 

changes the keyboard associated with windowf d’s desktop. Only the data per¬ 
tinent to the keyboard is used (i.e., screen->scr_kbdname). 

int 

win_setms(windowfd, screen) 
int windowfd; 

struct screen *screen; 

changes the mouse associated with windowf d’s desktop. Only the data per¬ 
tinent to the mouse is used (i.e., screen->scr_msname). 
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Arbitrary Devices 


Non-Vuid Devices 


Device Removal 


Device Query 


Arbitrary user input devices may be used to drive a workstation. However, some 
care must be exercised in selecting the combinations of devices. To install an 
input device with SunView, call win_set_input_device (). 

int 

win__set_input__device (windowfd, inputfd, name) 
int windowfd; 
int inputfd; 
char *name; 

windowfd identifies (by association) the workstation on which the input device 
is to be installed, name is used to identify the device on subsequent calls to Sun- 
View, e.g., Idevlkbd. name may only be SCRJNAMESIZE characters long. 
Before calling this routine, open the input device and make any ioctl(2) calls 
to it to set it up to your requirements, e.g. possibly setting the speed of the serial 
port through which the device in coming in on. Pass the open file descriptor in as 
inputfd. 

win_set_input_device () sends additional ioctl(2) calls to make the 
device operate as a Virtual User Input Device (if that is not its native mode) and 
operate in non-blocking read mode. The device’s unread input is flushed. Sun- 
View starts reading from the device. Once win_set_input_device () 
returns, close inputfd. This action won’t actually close the device; SunView 
has its own open file descriptor for the device. 

User input devices that only emit ASCII, and not vuid events, may be used by 
SunView. If the device does not respond to probing with the vuid ioctls Sun¬ 
View assumes it is an ASCII device and reads it one character at a time. 

Thus, SunView can handle input from a simple ASCII terminal without 
modification to any drivers. The routines in the section can be used with vuid or 
ASCII devices. 

To remove an input device from SunView, call 
win_remove_input_device(). 

int 

win_remove_input_device(windowfd, name) 
int windowfd; 
char *name; 

windowfd identifies the workstation from which to remove the input device, 
name identifies the device. SunView resets the device to its original state. 

To ask if an input device is being utilized by a workstation, call 
win_is_input_device(). 

int 

win_is_input_device(windowfd, name) 
int windowfd; 
char *name; 

windowfd identifies the workstation being probed, name identifies the device. 

0 is returned if the device is not being utilized, 1 is returned if it is, and -1 is 
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Device Enumeration 


7.3. Focus Control 


Keyboard Focus Control 


returned if there is an error. 

To ask what all the input devices of the workstation are, call 
win enum input_device () which enumerates them all. 

int 

win_enum_input_device(windowfd, func, data) 
int windowfd; 

int (*func)(); 

caddr_t data; 

windowfd identifies the workstation being probed. You pass the function 
func which is called once for every input device. The first argument passed to 
func () is a string which is the name of the device. The second argument 
passed to func () is data, which can be anything you want. If func returns 
something other than 0 the enumeration is terminated early. 
win_enum_input_device () returns -1 if there was an error during the 
enumeration, 0 if it went smoothly and 1 if func terminated the enumeration 
early. 

The concept of a split keyboard and pick input focus has been described in the 
SunView 1 Programmer’s Guide. The user interface documentation describes it 
as ’’click to type” mode. It allows keyboard input events to be directed to a dif¬ 
ferent window than the window that pick (cursor) inputs are sent to. Usually you 
want the keyboard input focus to stay in one window while the pick input focus 
is the window under the cursor. 

The following routine is called when a window gets a KBD_REQUEST event and 
the window doesn’t need the keyboard focus. 

win_refuse_kbd_focus(windowfd) 
int windowfd; 

The following routine is used to change the keyboard focus. It is only a hint; the 
target window can refuse the keyboard focus or the user may not be running in 
click-to-type mode. 

int 

win_set_kbd_focus(windowfd, number) 
int windowfd, number; 

number is the window that you want to have the keyboard focus. 

The following routine gets the window number of the window that is currently 
the keyboard focus. 

int 

win_get_kbd_focus(windowfd) 
int windowfd; 
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Event Specification 


Setting the Caret Event 


Getting the Caret Event 


Restoring the Caret 


This section describes how to programmatically specify which user actions are 
used as the focus control actions. The sunview(l) program has a set of flags to 
control the keyboard focus. 

One of the ways to change the keyboard focus is to set the caret. Setting the 
focus passes the focus change event through to the application. 

void 

win_set_focus_event(windowfd, fe, shifts) 
int windowfd; 

Firm_event *fe; 
int shifts; 

windowfd identifies the workstation, f e is a firm event pointer; the entire 
Firm_event structure is defined in the appendix titled Writing a Virtual User 
Input Device Driver . Only the id and the value fields are utilized in this call. 
The id field of *f e is set to the identifier of the event that is used to set the key¬ 
board focus, e.g., MS_LEFT. The value field is set to the value of the event 
that is used to set the keyboard focus, e.g., 0 (up) or 1 (down), shifts is a 
mask of shift bits that indicate the required state of the shift keys needed in order 
to have the event described by f e treated as the keyboard focus change event. 

-1 means that you don’t care. If you do care, use the same shift bits passed in the 
Event structure as discussed in the Handling Input chapter in the SunView 1 
Programmer's Guide, e.g., LEFTSHIFT. 

win_get_f ocus_event () returns the values set by 
win_set_focus_event(). 

void 

win_get_focus_event(windowfd, fe, shifts) 
int windowfd; 

Firm_event *fe; 
int *shifts; 

*f e and *shift s are filled in with the current values. 

Another ways to change the keyboard focus is to restore the caret. Restoring the 
focus swallows the focus change event so that it never makes it to the applica¬ 
tion. These two routines parallel the focus setting routines described above. 

void 

win__set_swallow__event (windowfd, fe, shifts) 
int windowfd; 

Firm_event *fe; 
int shifts; 


Event Specification 


Setting the Caret Event 


Getting the Caret Event 


Restoring the Caret 


void 


win_get_swallow_event(windowfd, fe, shifts) 
int windowfd; 

Firm_event *fe; 
int ^shifts; 
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This section discusses the concept of input synchronization in some detail. It’s 
an important but subtle system mechanism. You should understand it fully 
before changing the system’s default synchronization setting. 

When running with input synchronization enabled, only one input event is being 
consumed, or processed, at a time. This event is called the current event. Own¬ 
ership of the current event is bestowed by SunView to a single process; that pro¬ 
cess is said to have the current event lock. The lock belongs to a process, not a 
window device and is used to prevent any process from receiving an input event 
(via a read(2) system call) until the the lock has been released. This prevents 
race conditions between processes. This lets, for example, a user pop a window 
to the top and start typing to it before its image is drawn and have typing directed 
to the correct window. Input synchronization allows the process that currently 
has the lock to change its input mask and have the change recognized immedi¬ 
ately so that applications won’t miss events when they fall behind the user. 

Input synchronization is not to be confused with the management of the input 
focus. The input focus is that window which is supposed to get the next input 
event and the input synchronization mechanism is used to determine when the 
current input event processing is completed. 

The current event lock is acquired upon completing a read of a window device in 
which an input event was successfully read. For the duration of the lock, the 
current event lock owner decides what to do based on the current event and does 
it (or forks a process to do it). There is no notification to the input focus of input 
pending until the current event lock is released. Thus, there is typically only one 
process actively reading input at a time (except for rogue polling processes). 

Releasing the Current Event When a process finishes with the current event, the current event lock is released 

Lock via: 

□ A read(2) of the next event. If the next event is for the window that is 
doing the read then the lock is released and re-acquired immediately. 

□ A select(2) for input. This is the common case. 

□ An explicit win_release_event_lock () call (see below). 

An explicit lock release call is appropriate for an application that knows that it no 
longer needs to query the state of the virtual input device or change its input 
mask and is about to do something moderately time consuming. Such an appli¬ 
cation can explicitly release the lock as soon as it recognizes that the event it has 
just read is not going to change event distribution. 

win_release_event_lock(windowfd) 
int windowfd; 

Current Event Lock Breaking The current event lock is broken by SunView when the process with it visits the 

debugger or dies. 

In addition, SunView explicitly breaks the current event lock if an application 
takes too long to process the event. The time is measured in process virtual time, 
not real time. This is a quiet lock breaking in that no message is displayed and 
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no signal is sent to the offending process. The duration of the time limit can be 
set, for the entire workstation, to a range of values: 

□ 0 — Windows have rampant race conditions. There is poor performance on 
high speed mouse tracking because the system can’t compress mouse motion 
passed to applications. 

□ non-zero (approximately 1-10 seconds) — Most synchronization problems 
go away except when programs exceed the time limit. When SunView 
detects a process that exceeds the time limit the process temporarily goes 
into an unsynchronized mode until it catches up with the user. 

□ large-infinite (greater than 10 seconds) — Synchronization problems don’t 
arise. Unfortunately, the user is locked into just one program at a time 
echoing/noticing input The key combination 1 Setun-I I (the I Setup 1 key is 
the 1 Stop 1 key on Sun-2 and Sun-3 machines) explicitly breaks the lock. 

Getting/Setting the Event Lock The default time limit is 2 cpu seconds. You can get the current event lock 

Timeout timeout with a call to win_get_event_timeout (): 

void 

win_get_event_timeout(windowfd, tv) 
int windowfd; 

struct timeval *tv; 

*tv is filed in with the current value. 

You can set the current event lock timeout via a call to 
win_set_event_timeout (): 

void 

win_set_event_timeout(windowfd, tv) 
int windowfd; 

struct timeval *tv; 

*tv is used as the current value. 

7.5. Kernel Tuning Options Some kernel tuning variable are settable using a debugger. However, you are 

advised not to change these unless you absolutely have to. You can look at the 
kernel with a debugger to see the default settings of these values, but your are 
playing with fire. 

□ int ws_vq_node_byt es is the number bytes to use for the input queue. 
You might increase this number if you find your are getting “Window input 
queue overflow!” and “Window input queue flushed!” messages. This needs 
to be modified before starting SunView in order to have any affect. 

□ int ws_fast_timeout is the number of hertz between polls of input 

devices when in fast mode. SunView polls its input devices at two speeds. 
The fast mode is the normal polling speed and the slow mode occurs when 
no action has been detected in the input devices for 

ws_fast_j)oll_duration hertz. This is all meant to save cpu cycles of 
useless polling when the user is not doing anything. The system is con¬ 
stantly bouncing between slow and fast polling mode. 
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ws_f ast_t imeout should never be 0. Decreasing this number improves 
interactive cursor tracking at the expense of increased system polling load. 

□ int ws_s low_t imeout is the number of hertz between polls of input 
devices when in slow mode. ws_slow_t imeout should never be 0. 
Decreasing this number improves interactive cursor tracking at the expense 
of increased system polling load. 

o int ws_fast_poll_duration is discussed above. Increasing this 
number improves interactive performance at the expense of increased system 
polling load. 

□ int ws_loc_s t i 11 is the number of hertz after which, if the locator has 
been still, a LOC_STILL event is generated. 

o struct timeval ws_lock_limit is the process virtual time limit 
for a data or display lock. Increasing ws_lock_limit reduces the 
number of 

... lock broken after time limit exceeded ... 

console messages at the expense of slower response to dealing with lock 
hogs. 

□ int ws_check_lock and struct timeval ws_check_time 
The check for ws_lock_limit doesn’t start for ws_check_lock 
amount of real time after the lock is set. This is done to avoid system over¬ 
head for normal short lock intervals. Increasing ws_check_lock reduces 
system overhead on long lock holding situations at the expense of slower 
response to dealing with lock hogs. 

□ int win_disable_shared_locking is a flag that controls whether 
or not the window driver will try to reduce the overhead of display locking 
by using a shared memory mechanism. Even though there are no known 
problems with the shared memory locking mechanism, this variable is avail¬ 
able as an escape hatch. If the window system leaves mouse cursor drop¬ 
pings, set this variable to 1. The default is 0. Setting this variable to 1 will 
result in reduced graphics performance. 

□ int winclistchar smax is the maximum number of characters from 
the operating system’s “character buffer” pool that SunView is willing to 
utilize. Upping this number can reduce “tossed” input situations. Turning 
on wintossmsg (an int) will print a message if input has to be tossed, 
winclistcharsmax should only be increased by half again as much as 
its default. 

□ int ws_set_f avor is a flag that controls whether or not the window 
driver will try to boost the priority of the window process (and its children) 
that has the current event lock. The default is 1. In very tight memory situa¬ 
tions this dramatically improves interactive performance. 
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Changing the User Actions that The following is provided so that you can change the user actions for the various 
Affect Input real time interrupt actions. 

typedef struct ws_usr_async { 


short 

dont_touchl; 





short 

first_id; 

/* 

id of 

the 1st event */ 


int 

first_value; 

/* 

value 

of the 1st event 

*/ 

short 

second_id; 

/* 

id of 

the 2nd event */ 


int 

second__value; 

/* 

value 

of the 2nd event 

*/ 

int 

dont touch2; 






} Ws_usr_async 

Ws_usr_async ws_break_default = /* Event lock breaking */ 
{0, SHIFT_TOP, 1, TOP_FIRST + 'i', 1, 0}; 

Ws_usr_async ws_stop_default = /* Stop event */ 

{0, SHIFT_TOP, 1, SHIFT_TOP, 0, 0}; 

Ws_usr_async ws_flush_default = /* Input queue flushing */ 
{0, SHIFT_TOP, 1, TOP_FIRST + ', 1 , 0}; 
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Viewpoint 


Further Information 



Advanced Notifier Usage 


This chapter continues the description of the Notifier in The Notifier chapter of 
the SunView 1 Programmer’s Guide. 

This chapter presents areas which are not of general interest to the majority of 
SunView application programmers. These include: 

□ The registration of client, output and exception event handlers. 

□ Querying for the current address of one of a client’s event handlers. 

□ Interposition of any event handler. 

□ Controlling the order in which a client receives events. 

□ Control over the dispatching of events. 

□ Controlling the order in which clients are notified. 

□ A list of error codes. 

□ Restrictions on calls into the Notifier. 

□ A list of open issues surrounding the Notifier. 


Although the Notifier falls under the umbrella of SunView, the Notifier can be 
looked at as a library package that is usable separately from the rest of SunView. 
The viewpoint of this chapter is one in which the Notifier stands alone from Sun¬ 
View. However, there are notes about SunView’s usage of the Notifier 
throughout the chapter. 

You must read the chapter titled The Notifier in the SunView 1 Programmer’s 
Guide before you tackle this chapter; it has information and examples about the 
Notifier and SunView’s usage of it. In addition, The Agent & Tiles chapter in 
this manual has further information. 

This split description of the Notifier may be a little awkward for advanced users 
of the Notifier but is much less confusing for the majority of users. You should 
refer to the index in the SunView 1 Programmer’s Guide first and then the index 
in this book when using this material in a reference fashion. 
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8.2. Notification 

This section presents the programming interface to the Notifier that clients use to 
register event handlers and receive notifications. 

Links to the SunView 1 Programmer*s 
Guide. 

Only those areas not covered in the Notifier chapter of the SunView 1 
Programmer’s Guide are presented. In particular, input pending refers to the sec¬ 
tion in the other manual. 

The two Notifier chapters are different in that the SunView 1 Programmer’s 

Guide considers the Notifier in relation to SunView; thus, for example, in it 
notifier events are SunView Input Events, so their type is Event *. In this 
chapter, event is the more general type Notif y_event. 

Client Events 

This section describes how client events are handled by the Notifier. From the 
Notifier’s point of view, client events are defined and generated by the client. 
Client events are not interpreted by the Notifier in any way. The Notifier doesn’t 
detect client events, it just detects UNIX-related events. The Notifier is responsi¬ 
ble for dispatching client events to the client’s event handler after the event has 
been posted with the Notifier by application code (see the section entitled Post¬ 
ing below). 

Delivery Times 

The Notifier normally sends client event notifications when it is safe to do so. 

This may involve some delay between when an event is posted and when it is 
delivered. However, a client may ask to always be immediately notified of the 
posting of a client event (see Posting, below). 

Client Defined Signals 

The immediate client event notification mechanism should be viewed as an 
extension of the UNIX signaling mechanism in which events are client defined 
signals. However, clients are strongly encouraged to only use safe client event 
handlers. 

Handler Registration 

To register a client event handler call: 

Notify_func 

notify_set_event_func(client, event_func, when) 
Notify_client client; 

Notify_func event_func; 

Notify_event_type when; 

enum notify_event_type { 

NOTIFY_SAFE=0, 

NOTIFY IMMEDIATE=1, 

); 

typedef enum notify_event_type Notify_event_type; 

when indicates whether the event handler will accept notifications only when it 
is safe (NOTIFY_SAFE) or at less restrictive times (NOTIFY_IMMEDIATE). 16 


16 For a rundown of the basics of registering event handlers see the section on Event Handling in the Notifier 
chapter of the SunView 1 Programmer’s Guide. 
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The Event Handler 


SunView Usage 


Output Completed Events 


The calling sequence of a client event handler is: 

Notify_value 

event_func(client, event, arg, when) 

Notify_client client; 

Notify_event event; 

Notify_arg arg; 

Notify_event_type when; 

typedef caddr_t Notify_arg; 

in which client is the client that called not if y_set_event_f unc (). 
event is passed through from notif y_post_event ( ) (see Posting, 
below), arg is an additional argument whose type is dependent on the value of 
event and is completely defined by the client, like event, when is the actual 
situation in which event is being delivered (NOTIFY_SAFE or 
NOTIF Y_IMMED I ATE ) and may be different from when_hint of 
not if y_post_event (). The return value is one of NOTIFY_DONE or 
NOTIFY_IGNORED. 

You will almost certainly not need to directly register your own client event 
handler when using SunView. Window objects do this for themselves when they 
are created. However, note the following: 

□ A window has a client event handler that you may want to interpose in front 
of. See the section entitled Monitoring and Modifying Window Behavior in 
the Notifier chapter in the SunView 1 Programmer’s Guide. 

□ SunView client event handlers are normally registered with when equal to 
NOTIFY_SAFE. 

□ The Agent reads input events from a window’s file descriptor and posts them 
to the client via the win_post_event ( ) call. See the section titled 
Notifications From the Agent in The Agent & Tiles chapter. 


Notifications for output completed notifications are similar to input pending 
notifications, covered in the chapter on the Notifier in the SunView 1 
Programmer’s Guide. 

Notify_func 

notify_set_output_func(client, output_func, fd) 
Notify_client client; 

Notify_func output_func; 

int fd; 

Notify_value 
output_func(client, fd) 

Notify_client client; 
int fd; 
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Exception Occurred Events Exception occurred notifications are similar to input pending notifications. The 

only known devices that generate exceptions at this time are stream-based socket 
connections when an out-of-band byte is available. Thus, a SIGURG signal 
catcher is set up by the Notifier, much like SIGIO for asynchronous input. 

Notify_func 

notify_set_exception_func(client , exception_func, fd) 

Notify_client client; 

Notify_func exception_func; 

int fd; 

Notify_value 

exception_func(client, fd) 

Notify_client client; 

int fd; 


Getting an Event Handler Here is the list of routines that allow you to retrieve the value of a client’s event 

handler. The arguments to each notif y_get__*__func () function parallel 
the associated notif y_set_*_f unc () function described elsewhere except 
for the absence of the event handler function pointer. Thus, we don’t describe 
the arguments in detail here. Refer back to the associated 
notif y_set_*_f unc () descriptions for details. 17 

A return value of NOTIFY_FUNC_NULL indicates an error. If client is unk¬ 
nown then notif y_errno is set to NOTIFY_UNKNOWN_CLIENT. If no 
event handler is registered for the specified event then notif y_errno is set to 
NOTIFY_NO_CONDITION. Other values of notify__errno are possible, 
depending on the event, e.g., NOTIFY_BAD_FD if an invalid file descriptor is 
specified (see the associated notif y_set_*_f unc ()). 

Here is a list of event handler retrieval routines: 

Notify_func 

notify__get_input_func (client, fd) 

Notify_client client; 
int fd; 

Notify_func 

notify_get_event_func(client , when) 

Notify_client client; 

Notify__event__type when; 

Notify_func 

notify_get_output_func(client, fd) 

Notify_client client; 
int fd; 

Notify_func 


17 It is recommended that you use the Notifier’s interposition mechanism instead of trying to do 
interposition yourself using these notify_get_*_func () routines. 
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notify_get_exception_func(client, fd) 

Notify_client client; 
int fd; 

Notify_func 

notify_get_itimer_func(client, which) 
Notify__client client; 
int which; 

Notify_func 

not if y_get_signal__func (client, signal, mode) 
Not if y__client client ; 

int signal; 

Notify_signal_mode mode; 

Notify_func 

notify_get_wait3_func(client, pid) 
Notify_client client; 
int pid; 

Notify_func 

notify_get_destroy_func(client) 

Notify_client client; 
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8.3. Interposition 


Registering an Interposer 


NOTE 



There are many reasons why an application might want to interpose a function in 

the call path to a client’s event handler: 

□ An application may want to use the fact that a client has received a particular 
notification as a trigger for some application-specific processing. 

□ An application may want to filter the notifications to a client, thus modifying 
the client’s behavior. 

□ An application may want to extend the functionality of a client by handling 
notifications that the client is not programmed to handle. 

The Notifier supports interposition by keeping track of how interposition func¬ 
tions are ordered for each type of event for each client. Here is a typical example 

of interposition: 

□ An application creates a client. The client has set up its own client event, 
handler using notify_set_event_func (). 

□ The application tells the Notifier that it wants to interpose its function in 
front of the client’s event handler by calling 
notify_interpose_event_func () (described below). 

□ When the application’s interposed function is called, it tells the Notifier to 
call the next function, i.e., the client’s function, via a call to 
notify_next_event_func () (described below). 


The following routines let you interpose your own function in front of a client’s 
event handler. The arguments to each not if y_interpose_*_f unc () 
function parallel the associated not if y_set_*_func () function described 
above. Thus, we don’t describe the arguments in detail here. Refer back to the 
associated notify_set_*_func () descriptions for details. 

The one exception to this rule is that the arguments to 

not if y_interpose_itimer_f unc () are a subset of the arguments to 
notify_set_itimer_func(). 

Notify_error 

notify_interpose_input_func(client, input_func, fd) 
Notify_client client; 

Notify_func input_func; 
int fd; 

Notify_error 

notify_interpose_event_func(client, event_func, when) 
Notify_client client; 

Notify_func event_func; 

Notify_event_type when; 

Notify_error 

notify_interpose_output_func(client, output_func, fd) 
Notify_client client; 

Notify_func output_func; 

int fd; 
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Notify_error 

notify_interpose_exception_func(client, exception_func, fd) 
Notify_client client; 

Notify_func exception_func; 

int fd; 

Notify_error 

notif y_interpo se_i time r__f unc (client, itimer_func, which) 

Not if y__client client ; 

Notify__func itimer_func; 
int which; 


Notify__error 

notify_interpose_signal_func(client, 

signal, 

Notify_client 
Notify_func 
int 

Notif y__s igna l_mode 


client; 
signal_func; 
signal; 
mode ; 


signal_func, 

mode) 


Notify_error 

notify_interpose_wait3_func(client, wait3_func, pid) 
Not if y__client client ; 

Notify_func wait3_func; 

int pid; 


Notify_error 

notify_interpose__destroy_func(client, destroy_func) 
Notify__client client ; 

Notify_func destroy_func; 

The return values from these functions may be one of: 

□ NOTIFY_OK — The interposition was successful. 

□ NOTIFY__UNKNOWN_CLIENT — client is not known to the Notifier. 

□ NOTIF Y__NO_COND ITI ON —nn There is no event handler of the type 
specified. 

□ NOTIFY_FUNC_LIMIT — The current implementation allows five levels 
of interposition for every type of event handler, the original event handler 
registered by the client plus five interposers. NOTIFY_FUNC_JLIMIT indi¬ 
cates that this limit has been exceeded. 

If the return value is something other than NOTIFY_OK then not if y_errno 

contains the error code. 


Invoking the Next Function Here is the list of routines that you call from your interposed function in order to 

invoke the next function in the interposition sequence. The arguments and return 
value of each not if y_next_*_f unc () function are the same as the argu¬ 
ments passed to the your interposer function. Thus, we don’t describe the argu¬ 
ments in detail here. Refer back to the associated event handler descriptions for 
details. 
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Removing an Interposed 
Function 


Notify_value 

notify_next_input_func(client, fd) 

Not if y__client client ; 
int fd; 

Notify__value 

notify_next_event_func(client, event, arg, when) 
Notify__client client; 

Notify_event *event; 

Notify_arg arg; 

Not if y_event__type when ; 

Notify__value 

notify_next__output__func (client, fd) 

Notify_client client; 
int fd; 

Notify__value 

notify_next_exception_func(client, fd) 

Notify_client client; 
int fd; 

Notify__value 

notify_next_itimer_func(client, which) 

Notif y__client client ; 
int which; 

Notify__value 

notify_next_signal_func(client, signal, mode) 

Not if y__client client; 

int signal; 

Notify_signal_mode mode; 

Notify_value 

not if y__next__wait3_func (client, pid, status, rusage) 
Notif y__client client ; 
union wait status; 

struct rusage rusage; 
int pid; 

Notify__value 

notify_next_destroy_func(client, status) 
Notify_client client; 

Dest roy__status status ; 


Here is the list of routines that allow you to remove the interposer function that 
you installed using a notif y^interpose_*_f unc () call. The arguments 
to each notif y_remove_*_func () function is exactly the same as the asso¬ 
ciated notif y_set_*__f unc () function described above. Thus, we don’t 
describe the arguments in detail here. 
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NOTE The one exception to this rule is that the arguments to 


not if y_remove__i timer _f unc () are a subset of the arguments to 
notif y_set_itimer_func (). 

Notify__error 

notify_remove_input_func (client, input_func, fd) 
Notify_client client; 

Notify_func input__func; 
int fd; 

Notify_error 

notify_remove_event_func(client, event_func, when) 

Notify_client client; 

Notify_func event_func; 

Notify_event__type when; 

Notify_error 

notify_remove_output_func(client, output_func, fd) 

Not if y__client client ; 

Notify__func output_func; 
int fd; 

Notify__error 

not if y__remove__exception_f unc (client, except ion_f unc, fd) 
Notify_client client; 

Notify_func exception_func; 
int fd; 

Notify_error 

not if y_remove_itimer__f unc (client, itimer___func, which) 
Notify_client client; 

Notify_func itimer_func; 
int which; 

Notify_error 

notify_remove_signal__func(client, signal_func, signal, mode) 
Notify_client client; 

Notify_func signal_func; 

int signal; 

Notify__signal_mode mode; 

Notify___error 

notify_remove_wait3_func(client, wait3_func, pid) 
Notify_client client; 

Notify__func wait 3_f unc; 
int pid; 

Notify_error 

notify_remove_destroy_func(client, destroy_func) 
Notify_client client; 

Notify_func destroy_func; 
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If the return value is something other than NOTIFY_OK then not if y_errno 
contains the error code. The error codes are the same as those associated with 
notify_interpose_*_func () calls. 
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8.4. Posting 

This section describes how to post client events and destroy events with the 
Notifier. 

Client Events 

A client event may be posted with the Notifier at any time. The poster of a client 
event may suggest to the Notifier when to deliver the event, but this is only a 
hint. The Notifier will see to it that it is delivered at an appropriate time (more 
on this below). The call to post a client event is: 

typedef char * Notify_event; 

Notify_error 

notify_j?ost_event(client, event, when_hint) 

Notify_client client; 

Notify_event event; 

Notify_event_type when_hint; 

The client handle from notify set event func () is passed to 
notif y_j?ost_event (). event is defined and interpreted solely by the 
client. A return code of NOTIFY_OK indicates that the notification has been 
posted. Other values indicate an error condition. NOTIFY UNKNOWN CLIENT 
indicates that client is unknown to the Notifier. NOTIFY NO CONDITION 
indicates that client has no client event handler registered with the Notifier. 

Delivery Time Hint 

Usually it is during the call to notif y_post_event () that the client event 
handler is called. Sometimes, however, the notification is queued up for later 
delivery. The Notifier chooses between these two possibilities by noting which 
kinds of client event handlers client has registered, whether it is safe and what 
the value of when_hint is. Here are the cases broken down by which kinds of 
client event handlers client has registered: 

□ Immediate only — Whether when_hint is NOTIFY SAFE or 
NOTIFY_IMMEDIATE the event is delivered immediately. 

□ Safe only — Whether when_hint is NOTIFY_SAFE or 
NOTIFY_IMMEDIATE the event is delivered when it is safe. 

□ Both safe and immediate — A client may have both an immediate client 
event handler as well as a safe client event handler. If when hint is 
NOTIFY_SAFE then the notification is delivered to the safe client event 
handler when it is safe. If when_hint is NOTIFY IMMEDIATE then the 
notification is delivered to the immediate client event handler right away. If 
the immediate client event handler returns NOTIFY IGNORED then the 
same notification will be delivered to the safe client event handler when it is 
safe. 

Actual Delivery Time 

For client events, other than knowing which event handler to call, the main func¬ 
tion of the Notifier is to know when to make the call. The Notifier defines when 
it is safe to make a client notification. If it is not safe, then the event is queued 
up for later delivery. Here are the conventions: 

□ A client that has registered an immediate client event handler is sent a 
notification as soon as it is received. The client has complete responsibility 
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Posting with an Argument 


Storage Management 


for handling the event safely. It is rarely safe to do much of anything when 
an event is received asynchronously. Usually, just setting a flag that indi¬ 
cates that the event has been received is about the safest thing that can be 
done. 

o A client that has registered a safe client event handler will have a 

notification queued up for later delivery when the notification was posted 
during an asynchronous signal notification. Immediate delivery is not safe 
because your process, just before receiving the signal, may have been exe¬ 
cuting code at any arbitrary place. 

□ A client that has registered a safe client event handler will have a 
notification queued up for later delivery if the client’s safe client event 
handler hasn’t returned from processing a previous event. This convention 
is mainly to prevent the cycle: Notifier notifies A, who notifies B, who 
notifies A. A could have had its data structures tom up when it notified B 
and was not in a state to be reentered. 

Implied in these conventions is that a safe client event handler is called immedi¬ 
ately from other UNIX event handlers. For example: 

□ A client’s input pending event handler is called by the Notifier. 

□ Two characters are read by the client’s input pending event handler. 

□ The first character is given to the Notifier to deliver to the client’s safe event 
handler. 

a The Notifier immediately delivers the character to the client event handler. 

□ Returning back to the input pending event handler, the second character is 
sent. This character is also delivered immediately. 

SunView posts a fixed field structure with each event. Sometimes additional data 
must be passed with an event, for instance when the scrollbar posts an event to 
its owner to do a scroll. The scrollbars’ handle is passed as an argument along 
with the event, notif y_post_event_and_arg () provides this argument 
passing mechanism (see below). 

When posting a client event there is the possibility of delivery being delayed. In 
the case of SunView, the event being posted is a pointer to a structure. The 
Notifier avoids an invalid (dangling) pointer reference by copying the event if 
delivery is delayed. It calls routines the client supplies to copy the event infor¬ 
mation and later to free up the storage the copy uses, 
notif y_post_event_and_arg () provides this storage management 
mechanism. 
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SunView Usage 


Notify_error 

not if y_jpost__event_and_arg (client, event, when__hint, arg, 

copy_func, release_func) 
Notify_client client; 

Notify__event event; 

Notify_event__type when_hint ; 

Notify_arg arg; 

Notify_copy copy_func; 

Notify__release release_func; 


typedef caddr__t Notify_arg; 


typedef Notify_arg (*Notify_copy)(); 

#define NOTIFY_COPY_NULL ((Notify_copy)0) 


typedef void (*Notify_release)(); 

#define NOTIFY__RELEASE___NULL ( (Notify_release) 0) 

copy__f unc () is called to copy arg (and optionally event) when event 
and arg needed to be queued for later delivery, release_func () is called to 
release the storage allocated during the copy call when event and arg were no 
longer needed by the Notifier. 

Any of arg, copy_func () or release_func () may be null. If 
copy_f unc is not NOTIFY__COPY_NULL and arg is NULL then 
copy_func () is called anyway. This allows event the opportunity to be 
copied because copy_f unc () takes a pointer to event. The pointed to event 
may be replaced as a side affect of the copy call. The same applies to a non- 
NOTIFY_RELEASE_NULL release function with a NULL arg argument. 

The copy () and release () routines are client-dependent so you must write 
them yourself. Their calling sequences follow: 


Notify_arg 
copy_func(client, 
Notify_client 
Notify_arg 
Notify_event 


arg, event_ptr) 
client; 
arg; 

*event_j?tr; 


void 

release__func (client, arg, event) 

Notify_client client; 

Notify_arg arg; 

Notify__event event; 

There are Agent calls to post an event to a tile that provide a layer over the post¬ 
ing calls described here (see win_post_event () in the chapter entitled The 
Agent & Tiles). 
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Posting Destroy Events 


Delivery Time 


Immediate Delivery 


Safe Delivery 


When a destroy notification is set, the Notifier also sets up a synchronous signal 
condition for SIGTERM that will generate a DESTROY_PROCESS_DEATH des¬ 
troy notification. Otherwise, a destroy function will not be called automatically 
by the Notifier. One or two (depending on whether the client can veto your 
notification) explicit calls to notif y_post_destroy () need be made. 

Notify_error 

notify_post_destroy(client, status, when) 

Notify_client client; 

Destroy_status status; 

Notify_event_type when; 

NOTIFY_INVAL is returned if status or when is not defined. After notifying 
a client to destroy itself, all references to client are purged from the Notifier. 

Unlike a client event notification, the Notifier doesn’t try to detect when it is safe 
to post a destroy notification. Thus, a destroy notification can come at any time. 

It is up to the good judgement of a caller of notify_post_destroy () or 
notif y_die () (described in the section titled Notifier Control ) to make the 
call at a time that a client is not likely to be in the middle of accessing its data 
structures. 

If status is DESTROY_CHECKING and when is NOTIFY_IMMEDIATE then 
notify post destroy () may return NOTIFY_DESTROY_VETOED if the 
client doesn’t want to go away. 

Often you want to tell a client to go away at a safe time. This implies that 
delivery of the destroy event will be delayed, in which case the return value of 
not if y__post_destroy () can’t be NOTIFY_DESTROY_VETOED because 
the client hasn’t been asked yet. To get around this problem the Notifier will 
flush the destroy event of a checking/destroy pair of events if the checking phase 
is vetoed. Thus, a common idiom is: 

— 

(void) notify_post_destroy(client, DESTROY_CHECKING, 

NOTIFY_SAFE); 

(void) notify_post_destroy(client, DESTROY_CLEANUP, 

NOTIFY_SAFE); 

•._ J 
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8.5. Prioritization 

The Default Prioritizer 


Providing a Prioritizer 


The order in which a particular client’s conditions are notified may be controlled 
by providing a prioritizer operation. 18 


The default prioritizer makes its notifications in this order (any asynchronous or 
immediate notifications have already been sent): 

□ Interval timer notifications (ITIMER_REAL and then ITIMER_VIRTUAL). 

□ Child process control notifications. 

□ Synchronous signal notifications by ascending signal numbers. 

□ Exception file descriptor activity notifications by ascending fd numbers. 

□ Handle client events by order in which received. 

□ Output file descriptor activity notifications by ascending fd numbers. 

□ Input file descriptor activity notifications by ascending fd numbers. 


This section describes how a client can provide its own prioritizer. 


Notify_func 

notify_set_prioritizer_func(client, prioritizer_func) 
Notify_client client; 

Notify_func prioritizer_func; 


notif y_set_prioritizer_func () takes an opaque client handle and the 
function to call before any notifications are sent to client. The previous func¬ 
tion that would have been called is returned. If this function was never defined 
then the default prioritization function is returned. If the 
prior it izer_func () argument is NOTIFY_FUNC_NULL then no client 
prioritization is done for client and the default prioritizer is used. 

The calling sequence of a prioritizer function is: 


Notify_value 

prioritizer_func(client, nfd, ibits_ptr, obits_ptr, 

ebits_ptr, nsig, sigbits_ptr, auto_sigbits_ptr, 
event_count_ptr, events, args) 

Notify_client client; 

fd_set *ibits_ptr, *obits_ptr, *ebits_ptr; 

int nfd, nsig, *sigbits__ptr, 

* auto_sigbit s_pt r, *event_count_pt r; 

*events; 


Notify_event 
Notify_arg 


'"args; 


♦define SIG_BIT(sig) 


(1 « ((sig)-1)) 


in which client from notify set prioritizer_func () are passed to 
prioritizer_f unc (). In addition, all the notifications that the Notifier is 
planning on sending to client are described in the other parameters. This data 
reflects only data that client has expressed interest in by asking for 


18 It is anticipated that this facility will be rarely used by clients and that a client will rely on the ordering 
provided by the default prioritizer. 



microsystems 


Revision A, of May 9,1988 






82 SunView 1 System Programmer’s Guide 


Dispatching Events 


notification of these conditions. 

nf d describes the maximum number of valid bits in the f d_set structures 19 
pointed to by ibitsj>tr, obits_ptr, and ebits_ptr. ibits_ptr 
points to a bit mask of those file descriptors with input pending for client; 
similarly obit s_ptr points to a bit mask of file descriptors with output com¬ 
pleted, and ebits_ptr points to a bit mask of file descriptors on which an 
exception occurred, nsig describes the maximum number of valid bits in the 
arrays pointed to by sigbits_ptr and auto_sigbits_j?tr. 
si gbit s_pt r is a bit mask of signals received for which client has a condi¬ 
tion registered; the SIG_BIT macro can be used to access the correct bit. 
auto_sigbit s_j?tr is a bit mask of signals received that the Notifier is 
managing on behalf of client. event_count is the number of events in the 
array events, events is an array of pending client events and args is the 
parallel array of event arguments. 

The return value is one of NOTIFY_DONE or NOTIFY_IGNORED. These have 
their normal meanings: 

□ NOTIFY_DONE — All of the conditions had notifications sent for them. 
This implies that no further notifications should be sent to client this time 
around the notification loop. Unsent notifications are preserved for con¬ 
sideration the next time around the notification loop. 

□ NOT IFY_IGN0RED — A notification was not sent for one or more of the 
conditions, i.e., some notifications may have been sent, but not all. This 
implies that another prioritizer should try to send any remaining notifications 
to client. 

From within a prioritization routine, the following functions are called to cause 
the specified notifications to be sent: 

Notify_error 

notify_event(client, event, arg) 

Notify_client client; 

Notify_event event; 

Notify_arg arg; 

Notify_error 
notify_input(client, fd) 

Notify_client client; 
int fd; 

Notify_error 

notify_output(client, fd) 

Notify_client client; 
int fd; 

Notify_error 


19 With the increase past 32 of the maximum number of file descriptors under SunOS Release 4.0, the masks 
of FD bits are no longer ,ints but a special structure, defined in <sys /type s. h>. 
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notify_exception(client, fd) 
Notify_client client; 


int 


fd; 


Notify_error 

notify__itimer (client, which) 


Notify_client client; 


int 


which; 


Notify_error 

notify_signal(client, signal) 


Notif y__client client ; 


int 


signal; 


Notify_error 
notify_wait3(client) 

Notify_client client; 

The Notifier won’t send any notifications that it wasn’t planning on sending any¬ 
way, so one can’t use these calls to drive clients programmatically. A return 
value ofNOTIFY_OK indicates that client was sent the notification. A return 
value of NOTIFY_UNKNOWN_CLIENT indicates that client is not recognized 
by the Notifier and no notification was sent. A return value of 
NOTIFY__NO_CONDITION indicates that client does not have the requested 
notification pending and no notification was sent. 

A client may chose to replace the default prioritizer. Alternatively, a client’s 
prioritizer may call the default prioritizer after sending only a few notifications. 
Any notifications not explicitly sent by a client prioritizer will be sent by the 
default prioritizer (when called), in their normal turn. Once notified, a client will 
not receive a duplicate notification for the same event. 

Signals indicated by bits in sigbits_ptr should call notify_signal (). 
Signals in auto_sigbits_ptr need special treatment: 

□ SIGALRM means that notif y_itimer () should be called with a which 
Of ITIMER_REAL. 

□ SIGVTALRM means that notif y_itimer () should be called with a 
which of ITIMER__VIRTUAL. 

□ SIGCHLD means that notif y_wait3 () should be called. 

Asynchronous signal notifications, destroy notifications and client event 
notifications that were delivered right when they were posted do not pass through 
the prioritizer. 


Getting the Prioritizer 


notif y_get_prioritizer_func () returns the current prioritizer of a 
client. 


Notify_func 

notify_get_jprioritizer_func (client) 

Notify_client client; 

notif y_get_prioritizer_func () takes an opaque client handle. The 
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function that will be called before any notifications are sent to client is 
returned. If this function was never defined for client then a default function 
is returned. A return value of NOTIFY_FUNC_NULL indicates an error. If 
client is unknown then notif y_errno is set to 
NOTIFY UNKNOWN CLIENT. 
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8.6. Notifier Control 

Starting 


Stopping 

Mass Destruction 


The following are the Notifier wide (vs single condition) operations. 


Here is the routine for starting the notification loop of the Notifier: 

Notify_error 
notify_start() 

This is the main control loop. It is usually called from the main routine of your 
program after all the clients in your program have registered their event handlers 
with the Notifier . 20 The return values are: 

□ NOTlFY_OK — Terminated normally by notify_stop () (see below). 

□ NOTIFY_NO_COND ITI ON — There are no conditions registered with the 
Notifier. 

o NOTIFY_INVAL — Tried to call notif y_start () before returned from 
original call, i.e., this call is not reentrant 

□ NOTIFY_BADF — One of the file descriptors in one of the conditions is not 
valid. 

An application may want to break the Notifier out its main loop after the Notifier 
finishes sending any pending notifications. 

Notify_error 
notify_stop() 

This causes notify_start () to return. The return values are NOTIFY_OK 
(will terminate notif y_start () ) and NOTIFY_NOT_STARTED 
(notify_start () not entered). 

The following routine causes the all client destruction functions to be called 
immediately with status: 

Notify_error 
notify_die(status) 

Destroy_status status; 

This causes the all client destruction functions to be called immediately with 
status as the reason. The return values are NOTlFY_OK or 
NOTlFY_DESTROY_VETOED; the latter indicates that someone called 
notif y_veto_destroy () and status was DESTROY_CHECKING. It is 
then the responsibility of the caller of notif y_die () to exit the process, if so 
desired. See the discussion on not if y_post_destroy () for more informa¬ 
tion. 


20 SunView programs usually call window_main_loop() instead of notify_start (). 
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Scheduling 

There is the mechanism for controlling the order in which clients are notified. 
(Controlling the order in which a particular client’s notifications are sent to it is 
done by that client’s prioritizer operation; see the Prioritization section earlier.) 

Notify_func 

notify set_scheduler_func(scheduler_func) 

Notify_func scheduler_func; 

notify set scheduler f unc () allows you to arrange the order in which 
clients are called. (Individual clients can control the order in which their event 
handlers are called by setting up prioritizers.) 

notify set scheduler_func () takes a function to call to do the 
scheduling of clients. The previous function that would have been called is 
returned. This returned function will (almost always) be important to store and 
call later because it is most likely the default scheduler. 

Replacement of the default scheduler will be done most often by a client that 
needs to make sure that other clients don’t take too much time servicing all of 
their notifications. For example, if doing “real-time” cursor tracking in a user 
process, the tracking client wants to schedule itself ahead of other clients when¬ 
ever there is input pending on the mouse. 

The calling sequence of a scheduler function is: 

Notify_value 

scheduler_func(n, clients) 
int n; 

Notify_client *clients; 

in which a list of n clients, all of which are slated to receive some notification 
this time around, are passed into scheduler_f unc (). The scheduler scans 
clients and makes calls to notif y_client () (see below). Clients so 
notified should have their slots in clients set to NOTIFY_CLIENT_NULL. 
The return value from scheduler_f unc () is one of: 

□ NOTIFY DONE — All of the clients had a chance to send notifications. 

This implies that no further clients should be scheduled this time around the 
notification loop. Unsent notifications are preserved for consideration the 
next time around the notification loop. 

□ NOTIFY IGNORED — One or more clients were scheduled, i.e., some 
clients may have been scheduled, but not all. This implies that another 
scheduler should try to schedule any clients in client s that are not 
NOTIFY_CLIENT_NULL. 

Dispatching Clients 

The following routine is called from scheduler routines to cause all the pending 
notifications for client to be sent: 

Notify_error 
notify_client(client) 

Notify_client client; 

The return value is one of NOTIFY_OK (client notified) or 

NOTIFY NO CONDITION (no conditions for client, perhaps 
notify client () was already called with this client handle) or 
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NOTIFY_UNKNOWN__CLIENT (unknown client). 


Getting the Scheduler 


The following routine returns the function that will be called to do client schedul¬ 
ing: 


Notify__func 

notify_get_scheduler__func () 


This function is always defined to at least be the default scheduler. 


Client Removal 


A client can remove itself from the control of the Notifier with 


notify__remove (): 

Notify_error 
notify_remove(client) 

Notif y__client client ; 

notif y_remove () is a utility to allow easy removal of a client from the 
Notifier’s control. All references to client are purged from the Notifier. This 
routine is almost always called by the client itself. The return values are 
NOTIFYJDK (success) and NOTIF Y_UNKN 0 WN_C LIE NT (unknown client). 
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8.7. Error Codes This section describes the basic error handling scheme used by the Notifier and 

lists the meaning of each of the possible error codes. Every call to the Notifier 
returns a value that indicates success or failure. On an error condition, 
notif y_errno describes the failure, not if y_errno is set by the Notifier 
much like errno is set by UNIX system calls, i.e., not if y_errno is set only 
when an error is detected during a call to the Notifier and is not reset to 
NOTIFY_OK on a successful call to the Notifier. 

enum notify_error { 

... /* Listed below */ 

}; 

typedef enum notify_error Notify_error; 

extern Notify_error notify_errno; 

Here is a complete list of error codes: 

□ NOT IF Y_OK — The call was completed successfully. 

□ NOTIFY_UNKNOWN_CLIENT — The client argument is not known by 
the Notifier. A notif y_set_*_func type call need be done in order for 
the Notifier to recognize a client. 

□ NOTIFY_NO_CONDITION — A call was made to access the state of a con¬ 
dition but the condition is not set with the Notifier for the given client. This 
can arise when a notify_get_*_func () type call was done before the 
equivalent notif y_set_*_f unc () call was done. Also, the Notifier 
automatically clears some conditions after they have occurred, e.g., when an 
interval timer expires. 

□ NOTIFY_BAD_ITIMER — The which argument to an interval timer rou¬ 
tine was not valid. 

□ NOTIFY_BAD_SIGNAL — The signal argument to an signal routine 
was out of range. 

□ NOTIFY_NOT_STARTED — A call to notify_stop () was made but 
the Notifier was never started. 

□ NOTIFY_DESTROY_VETOED — A client refused to be destroyed during a 
call to notify_die () or notif y_post_destroy () when status 
was DESTROY__CHECKING. 

□ NOTIFY_INTERNAL_ERROR — This error code indicates some internal 
inconsistency in the Notifier itself has been detected. 

□ NOTIFY_SRCH — The pid argument to a child process control routine 
was not valid. 

□ NOTIFY_BADF — The f d argument to an input or output routine was not 
valid. 

□ NOTIFY_NOMEM — The Notifier dynamically allocates memory from the 
heap. This error code is generated if the allocator could not get any more 
memory. 
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□ NOTIFY_lNVAL — Some argument to a call to the Notifier contained an 
invalid argument. 

□ NOTIFY_FUNC_LIMlT — An attempt to set an interposer function has 
encountered the limit of the number of interposers allowed for a single con¬ 
dition. 

The routine not if y_j>error () acts just as the library call perror(3). 

notify_perror(str) 
char *str; 

notify_perror () prints the string str, followed by a colon and followed 

by a string that describes notif y_errno to stderr. 
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8.8. Restrictions on 

Asynchronous Calls 
into the Notifier 


The Notifier takes precautions to protect its data against corruption during calls 
into it while it is calling out to an asynchronous/immediate event handler. The 
Notifier may issue an asynchronous notification for an asynchronous signal con¬ 
dition, an immediate client event condition or a destroy condition. Most calls 
from event handlers back into the Notifier are permitted, but there are some res¬ 
trictions: 

□ Some calls are not permitted. In particular, they are: 

notify_start() 
notify_client() 


□ Only a certain number of calls into the Notifier are permitted. This restric¬ 
tion is due to how the Notifier handles memory management in a safe way 
during asynchronous processing. As a guideline, do not do more than five 
calls of the notif y_set_*_f unc (), 

notify_interpose_*_func() or notify post *() variety dur¬ 
ing an asynchronous notification. 


The Notifier is not prepared to handle calls into it from signal catching rou¬ 
tines that a client has set up with signal(3) or sigvec(2). 


Nr microsystems 


Revision A, of May 9,1988 






Chapter 8 — Advanced Notifier Usage 91 


8.9. Issues Here are some issues surrounding the Notifier: 

□ The layer over the UNIX signal mechanism is not complete. Signal blocking 
(sigblock(2)) can still safely be done in the flow of control of a client to 
protect critical portions of code as long as the previous signal mask is 
restored before returning to the Notifier. Signal pausing (sigpause(2)) is 
essentially done by the Notifier. Signal masking (sigmask(2)) can be 
accomplished via multiple notif y_set_signal_f unc ( ) calls. Set¬ 
ting up a process signal stack (sigstack(2)) can still be done. Setting the 
signal catcher mask and on-signal-stack flag (sigvec(2)) could be done by 
reaching around the Notifier but is not supported. 

□ Not all process resources are multiplexed (e.g., rlimit(2), set jmp(2), 
umask(2), setquota(2), and setpriority(2)), only ones that have to 
do with flow of control multiplexing. Thus, some level of cooperation and 
understanding need exist between packages in the single process. 

□ One can make a case for intercepting close(2) and dup(2) calls so that the 
Notifier is not waiting on invalid or incorrect file descriptors if a client for¬ 
gets to remove its conditions from the Notifier before making these calls. 

□ One can make a case for intercepting signal(3) and sigvec(2) calls so 
that the Notifier doesn’t get confused by programs that fail to use the 
Notifier to manage its signals. 

□ One can make a case for intercepting set itimer(2) calls so that the 
Notifier doesn’t get confused by programs that fail to use the Notifier to 
manage interval timers. 

□ One can make a case for intercepting ioctl(2) calls so that the Notifier 
doesn’t get fouled up by programs that use FIONBIO and FIOASYNC 
instead of the equivalent f cnt 1(2) calls. 

□ One can make a case for intercepting readv(2) and wr ite(2) just like 
read(2) and select(2) so that a program doesn’t tie up the process. 

□ The Notifier is not a lightweight process mechanism that maintains a stack 
per thread of control. However, if such a mechanism becomes available then 
the Notifier will still be valuable for its support of notification-based clients. 

□ Client events are disjoint from UNIX events. This is done to give complete 
freedom to clients as to how events are defined. One could imagine certain 
clients wanting to unify client and UNIX events. This could be done with a 
layer of software on top of the Notifier. A client could define events as 
pointers to structures that contain event codes and event specific arguments. 
The event codes would include the equivalents of UNIX event notifications. 
The event specific arguments would contain, for example, the file descriptor 
of an input-pending notification. When an input-pending notification from 
the the Notifier was sent to a client, the client would turn around and post the 
equivalent client event notification. 

□ One could imagine extending the Notifier to provide a record and replay 
mechanism that would drive an application. However, this is not supported 
by the current interface. 
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The Selection Service and Library 


9.1. 




Introduction 


The Selection Service package provides for flexible communication among win¬ 
dow applications. It is concerned with aspects of the selection[s] the user has 
made, and with the status of the user interface which may affect those selections. 
It has 3 distinct aspects: 

1. A server process maintains a clearinghouse of information about the selec¬ 
tion, and the function keys which may affect how a selection is made. This 
process responds to RPC requests for information from clients. Normally, 
the RPC accesses will be done only by library routines described below; 
therefore details of that access do not appear in this manual. 

2. A library of client routines is provided to communicate with the clearing¬ 
house process and with each other. These routines allow a client to acquire a 
selection, or yield it to another application, to determine the current holder 
of a selection, and send or receive requests concerning a selection’s contents 
and attributes. 

3. A minimal set of requests is defined for communicating between applica¬ 
tions which have some interest in the selection. This set is deliberately 
separated from the transport mechanism mentioned under (2) above, and the 
form of a request is carefully separated from its content. This allows appli¬ 
cations to treat the definition of what can be said about the selection as 
open-ended; anything consenting applications agree to can be passed 
through the Selection Service. 

This chapter is primarily concerned with the transport library, and how to use 
that protocol to accomplish representative application tasks. The (current) set of 
generic requests is also presented, and used in illustrations. 

The next sections is a fast overview of how the Selection Service works, and a 
walk-through of the complex protocol followed when selections are transferred 
between client. This is followed by several discursive sections devoted to partic¬ 
ular aspects of using the Selection Service, such as reporting function-key transi¬ 
tions, sending requests, acquiring and releasing selections, replying to requests, 
and debugging selection applications. Throughout these sections, some pro¬ 
cedures and data types are mentioned or described. Full documentation for all of 
these may be found in the reference section which follows. Finally there are two 
example programs which show how to use the Selection Service for simple 
queries (get_selection) and how a real client of the selection service works 
(selndemo). 
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The remainder of the chapter comprises reference material: descriptions of the 
public data and procedures of the selection library, a list of the defined common 
attributes, and the complete source of a program to retrieve the contents of a 
selection and print it on stdout. 

9.2. Basic Concepts When a user makes a selection, it is some application program which interprets 

the mouse and function-key events and resolves them into a particular selection. 
The Selection Service is involved only as the processing of function-keys and 
selections spans application windows. Application programs interact with the 
package in proportion to the sophistication of their requirements. This section is 
intended to present the information necessary for any use of the Selection Ser¬ 
vice, and to indicate what further information in the document pertains to various 
uses of the package. 

The selection library deals with four objects under the general term “ selection .” 
Most familiar is the Primary selection, which is normally indicated on-screen by 
inverting (“highlighting”) its contents. Selections made while a function key is 
held down (usually indicated with an underscore) are Secondary selections. The 
selection library treats the Shelf 21 (the global buffer which is loaded by Cut 22 
and Copy operations, and which may be retrieved by a Paste operation) as a 
third kind of selection. Finally, the insertion point, or Caret, is also treated as a 
selection, even though it has no contents. These are the four ranks the selection 
library deals with: Caret, Primary, Secondary, and Shelf. 

Every selection has a holder, this is a piece of code within a process which is 
responsible for operating on the selection and responding to other applications’ 
requests about it. A selection holder is a client of the selection library. Typi¬ 
cally, a selection client is something like a subwindow; there may be several 
selection clients within a single process. 

Because the selection library uses RPC as well as the SunView input system, it 
relies on the SunView Notifier to dispatch events; thus any application using the 
selection library must be built on the notifier system. 

9.3. Fast Overview The simplest use of the Selection Service is to inquire about a selection held by 

some other application. Programs which never make a selection will not use the 
facilities described in the rest of this section. Much of the material remaining 
before the beginning of reference section is likewise irrelevant to these programs: 
the sections on Acquiring and Releasing Selections and Callback Procedures 
pertain only to clients which make selections. 

A program which will actually make selections should be a full-fledged client of 
the selection library. Such an application calls seln_create () during the 
client’s initialization routines; if successful, this returns an opaque client handle 
which is then passed back in subsequent calls to selection library procedures. 


21 The shelf is called the Clipboard in user-oriented documentation such as the SunView 1 Beginner's 
Guide , and in the text subwindow menu. 

22 Prior to SunOS Release 4.0, the terms Delete t Put t and Get were used instead of the “industry-standard” 
Cut, Copy, and Paste. 
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The Selection Service vs. the 
Selection Library 


9.4. Selection Service 

Protocol: an Example 


Secondary Selection Between 
Two Windows 


Two arguments to this create-procedure specify client callback procedures which 
may be called to perform processing required by external events. These are the 
function_j?roc () and the reply_proc () described below. 

Note the difference here between the Selection Service program, and the selec¬ 
tion library. The former is a separate program, selection_svc(l), the latter 
is the code in a SunView application which knows how to talk to the Selection 
Service and its other clients. After a client is successfully created, it may call 
library routines to: 

□ inquire of the Selection Service how to get in touch with the holder of a par¬ 
ticular rank of selection, 

□ send a request to such a holder (e.g. to find out the contents of a selection), 

□ inform the Selection Service of any change in the state of the function keys 

□ acquire a selection, and later, 

□ release a selection it has acquired. 

The client must be prepared to deal with: 

□ reports from the Selection Service of function key transitions it may be 
interested in (these are handled by its function_proc ( )) 

□ requests from other clients about selections it holds (these are handled by its 
reply_proc ()). 

Finally, when the client is finished, it calls seln_destroy () to clean up its 
selection library resources. 

It’s important to remember that the Selection Service is an external process 
which client programs talk to to find out about the selections held by other 
clients. To clarify the conceptual model, here’s an outline of the communication 
which takes place when a user makes a secondary selection between two win¬ 
dows. 

Try the sequence out yourself while you read the description; The following 
description assumes that you have a standard set-up (focus follows cursor, adjust¬ 
ing selections does not make them pending-delete, left mouse button is select, 
middle is extend/adjust, etc.). If you have trouble performing the operation, the 
SunView 1 Beginner’s Guide has more to say on selections. 

1. Move the cursor into one text subwindow (call it “window A”). Note how 
the border of the subwindow darkens. 

2. Click LEFT in window A to select a character. Window A sets the caret and 
highlights the primary selection you have just made. 

3. Hold down the I Paste I key (usually [ L8) ). 

4. Move the cursor into another text subwindow (call it “window B”). 

5. Click LEFT and MIDDLE in window B to select some text. Note how it 
underlines the selection to indicate that it is a secondary selection. 


The Selection Service vs. the 
Selection Library 


9.4. Selection Service 

Protocol: an Example 


Secondary Selection Between 
Two Windows 
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6. Release the 1 Paste 1 key. Note how the secondary selection from window B 
appears at the caret in window A. 

Here’s what happens internally when this sequence of user actions takes place. 
Assume window A and B have registered as clients of the Selection Service 
using seln_create (). The initial state is no function keys down, and no one 
holds any of the selections. 

Table 9-1 Selection Service Scenario 
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Table 9-1 Selection Service Scenario — Continued 


Client A Selection Service 

Client B Notes 

User presses left mouse button (but has not released yet). 

seln_acquire( 3 

UNSPECIFIED) 


Check state of function keys; 
since I Paste I is Down, note caller 
as secondary holder; return 


secondary. 

Provide feedback to indicate 
secondary selection at indicated 
point If user has held down the 

1 Control 1 kev. secondary selec- 
tion may be pending-delete. 

User releases left mouse button. 

no action required 

User presses middle mouse button (but has not released yet). 

provide feedback for adjustment 
of secondary selection 

User releases middle mouse button. 

no action required 

User releases [Paste] key. 


Note that this key-up leaves all 
function keys up. Figure out 
which of the four selection hold¬ 
ers to notify (the primary selec¬ 
tion holder, A). 

seln_report_event(B, 
up-event) 

B’s call to 

seln_report_event() 
gets notification in return; B 
calls seln_f igure- 
_response (), which says 

IGNORE 


#sun 
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Table 9-1 Selection Service Scenario — Continued 


Notes 


Client B 


Selection Service 


Client A 


Window A’s 

function_proc () is called 
(it was registered with the 
Selection Service in 
seln_create () to handle 
reported function key transi¬ 
tions). The 

function_jproc () in turn 
calls 

seln_figure_response(), 
which tells it to request the con¬ 
tents of the secondary selection 
from the secondary selection 
holder. 

So function_j?roc () calls 
seln_init_request () to 
set up a request to 

a) get the contents of the secon¬ 
dary selection, 

b) commit any pending-delete, 
and yield secondary; 

It then calls 

seln_request () to send 
this request to B. 


The request arrives as an RPC 
call to B’s request-proc () 
(likewise registered with the 
Selection Service in 
seln_create (), but the 
reply proc handles requests 
about selections). B provides 
response to each attribute in the 
request; in response to the 
request to Yield(secondary), it 
calls seln done ( 


SELN SECONDARY) 


Note there is no holder of the 
secondary selection. 


Do pending delete if necessary: 
remove selection; cache con¬ 
tents; call seln_acquire ( 


SELN SHELF) 


Note caller as holder of the Shelf. 


Return from rpc call. 
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Table 9-1 

Selection Service Scenario — Continued 



Client A 

Consume response, inserting 
contents; if primary selection 
were pending delete, then 
would delete primary (supersed 
ing B as holder of Shelf if so). 

Selection Service 

Client B 

Notes 

Notes on the Above Example 

1. To be absolutely correct, clients should determine whether they want the 
Caret when they get a KBD_USE event, and acquire it immediately if so. 
Code to do this would look something like 

Client A 

Selection Service 

Client B 

Notes 

User moves cursor into window A. 

Get KBD USE event. 

Call seln_get_- 
function_state() 

seln_acquire( 
SELN_CARET) 

Return state of function keys 
(all up). 




But this would involve waking up a client every time the cursor crossed its win¬ 
dow; further, the kernel sends spurious KBD_USEs on window-crossings when a 
function key is down; Hence most clients postpone acquiring the Caret until they 
know they have input. For most clients, input is usually signalled by a key going 
down (either a function-key or a regular ASCII-key). 

2. Some window types acquire the Caret and primary selection at this point, so 
they simply call seln_acquire (client handle, 

SELN_UNSPECIFIED) when a key goes down. 

3. This “Point Down” describes what most windows implement, as opposed to 
the first theoretical exchange. The issue is whether clients call 
seln_inquire (client, SELN_UNSPECIFIED) , and then acquire the 
appropriate selection, or whether they should simply call 
seln_acquire (client, SELN_UNSPECIFIED). 


When an application makes a selection, its rank depends on the state of the func¬ 
tion keys. (A secondary selection is one made while a function key is held 
down.) The application which is affected by a function-key transition may not be 
the one whose window received that transition. Consequently, this system 
requires that the service be informed of transitions on those function keys that 
affect the rank of a selection; the service then provides that state information to 


9.5. Topics in Selection 
Processing 

Reporting Function-Key 
Transitions 
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any application which inquires. 

The keys which affect the rank of a selection are [ Copy) , 1 Paste I . [Cut I . and 
fFindl (ordinarily these are keys (L0, (HD, IL1Q1 , and CGD, respectively). If an 
application program does not include these events in its input mask, then they 
will fall through to the root window, and be reported by it. But if the application 
is reading these events for any reason, then it should also report the event to the 
service. seln_report_event () is the most convenient procedure for this 
purpose; seln_inf orm () does the work at a lower level. 

When the service is told a function key has gone up, it will cause calls to the 
function_proc callback procedures of the holders of each selection. For the client 
that reports the key-up, this will happen during the call to 
seln_report_event; for other holders, it can happen any time control 
returns to the client’s notifier code. The required processing is detailed under 
Callback Procedures below. Programs which never called seln_create () 
can call seln_report_event () without incurring any extra processing — 
they have no function_proc to call.) 

Two procedures are provided so that clients may interrogate state of the functions 
keys as stored by the service: seln_get_function_state () takes a 
Seln_f unction and returns TRUE or FALSE as the service believes that 
function key is down or not. seln_f unctions_state () takes a pointer to a 
Seln_functions_state buffer (a bit array which will be all 0 if the service 
believes all function keys are currently up). 

Sending Requests to Selection 

Holders 


Inside the selection library, a request is a buffer (a Seln_request structure); 
the following declarations are relevant to the processing that is done with such a 
buffer: 

typedef struct { 

Seln_result (*consume)(); 

char 

} Seln_requester; 

typedef struct { 

Seln_replier_data 
Seln_requester 
char 

Seln_rank 
Seln_result 
unsigned 
char 

} Seln_request; 


*context; 


*replier; 

requester; 

*addressee; 
rank; 
status; 
buf_size; 

data[SELN_BUFSIZE]; 


Clients of the Selection Service inquire of it who holds a particular rank of selec¬ 
tion using seln_inquire (); they then talk directly to each other through 
request buffers. A client loads an attribute value list of its requests about the 
rank of selection into these buffers. Requests include things like “What are the 
contents of the selection?”, “What line does the selection start on?”, “Please give 
up the selection (I need to highlight)!”, and so forth. 
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/* VARARGS */ 

Seln_request * 

seln_ask(holder, <attributes>, ... 0) 

Seln_holder ^holder; 

Attr_union attribute; 

/* VARARGS */ 
void 

seln_init_request(buffer, holder, <attributes>, ... 0) 
Seln_request *buffer; 

Seln_holder ^holder; 

char ^attributes; 


/* VARARGS */ 
Seln_result 
seln_query(holder, 
Seln_holder 
Seln_result 
char 

Attr union 


reader, context, <attributes>, 
*holder; 

(^reader) () ; 

^context; 
attribute; 


0 ) 


Seln__result 
reader(buffer) 

Seln_request *buffer; 

The selection library routines pass request buffers from clients to the particular 
client who holds that rank of selection. That client returns its reply in one or 
more similar buffers. The library is responsible for maintaining the dialogue, but 
does not have any particular understanding of the requests or their responses. 

seln_query () (or seln_ask (), for clients unwilling to handle replies of 
more than one buffer) is used to construct a request and send it to the holder of a 
selection. 

There is a lower-level procedure, seln_request () which is used to send a 
pre-constructed buffer containing a request, and an initializer procedure, 
seln_init_request () which can be used to initialize such a buffer. 

The data portion of the request buffer is an attribute-value list, copied from the 
<attributes> . . . arguments in a call to seln_query ( ) or 
seln_ask () . A similar list is returned in the reply, typically with real values 
replacing placeholders provided by the requester. (It may take several buffers to 
hold the whole reply list; this case is discussed below.) 

The request mechanism is quite general: an attribute-value pair in the request 
may indicate some action the holder of the selection is requested to perform — 
even a program to be executed may be passed, as long as the requester and the 
holder agree on the interpretation. 

The header file <suntool/selection__attributes . h> defines a base set 
of request attributes; a copy is printed near the end of this chapter. The most 
common request attribute is S E LN_REQ_CONTENT S_AS C11, which requests 
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the holder of the selection to return its contents as an ASCII string. 

Long Request Replies 

If the reply to a request is very long (more than about 2000 bytes), more than one 
buffer will be used to return the response. In this case, seln_ask () simply 
returns a pointer to the first buffer and discards the rest. 

NOTE 

This means that that the attribute value list in the first buffer may not be properly 
terminated (but it probably will be). 

seln_query () should be used if long replies are to be handled gracefully. 
Rather than returning a buffer, it repeatedly calls a client procedure to handle 
each buffer in turn. The client passes a pointer to the procedure to be called in 
the reader argument of the call to seln_query () (that address appears in 
the consume element of the Seln_requester struct.) Such procedures 
typically need some context information to be saved across their invocations; this 
is provided for in the context element of the Seln_requester structure. 
This is a 32-bit datum provided for the convenience of the reader procedure; it 
may be filled in with literal data or a pointer to some persistent storage; the value 
will be available in each call to reader, and may be modified at will. 

Selection holders are responsible for processing and responding to the attributes 
of a request in the order they appear in the request buffer. Selection holders may 
not recognize all the attributes in a request; there is a standard response for this 
case: In place of the unrecognized attribute (and its value, if any), the replier 
inserts the attribute SELN_REQ_UNRECOGNI ZED, followed by the original 
(unrecognized) attribute. This allows heterogeneous applications to negotiate the 
level at which they will communicate. 

A straightforward example of request processing (including code to handle a long 
reply) is the get_selection program, which appears at the end this chapter. 

Acquiring and Releasing 
Selections 

Applications in which a selection can be made must be able to tell the service 
they now hold the selection, and they must be able to release a selection, either 
on their own initiative, or because another application has asked to acquire it. 
Seln_acquire is used both to request a current holder of the selection to 
yield, and then to inform the service that the caller now holds that selection. 
seln_yield() is used to yield the selection on the caller’s initiative. A 
request to yield because another application is becoming the holder is handled 
like other requests; this is discussed under Callback Procedures below. 

Callback Procedures: 
Function-Key Notifications 

When you register a client with the Selection Service using seln_create (), 
you must supply a function_proc() and a reply_proc(). The former is called by 
the Selection Service to report function-key transitions (which may have 
occurred in other windows) to the client; the latter is called by the Selection Ser¬ 
vice when this client holds one of the selections and other clients have requests 
about it. 

The selection library calls the client’ s function_proc() when the Selection Service 
is informed of a function-key transition which leaves all function keys up. This 
may happen inside the client’s call to seln_report_event (), if the report¬ 
ing client holds a selection; otherwise the call will arrive through the RPC 
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mechanism to the function_proc (). 

The relevant declarations are: 

typedef enum { 

SELN_IGNORE, SELN_REQUEST, SELN_FIND, 

SELN_SHELVE, SELN_DELETE 
} Seln_response; 

typedef struct { 

Seln_f unction function; 

Seln_rank addressee_rank; 

Seln_holder caret; 

Seln_holder primary; 

Seln_holder secondary; 

Seln_holder shelf; 

} Seln_function_buffer; 

Seln_response 

seln_figure_response(buffer, holder) 

Seln_function_buffer *buffer; 

Seln_holder **holder; 

void 

function_proc(client_data, function) 
char *client_data; 

Seln_function_buffer *function; 

f unction_j?roc () will be called with a copy of the 32 bits of client data ori¬ 
ginally given as the third argument to seln_create (), and a pointer to a 
Seln_f unct ion_buf f er. The buffer indicates what function is being 
invoked, which selection the called program is expected to be handling, and what 
the Selection Service knows about the holders of all four selection ranks (one of 
whom is the called program). A client will only be called once, even if it holds 
more than one selection. (In that case, the buffer’s addressee_rank will 
contain the first rank the client holds.) 

Responding to Selection 

Requests 

The holders of the selections are responsible for coordinating any data transfer 
and selection-relinquishing among themselves. The procedure 
seln_f igure_response () is provided to assist in this task. It takes a 
pointer to a function buffer such as the second argument to a function proc 
callback, and a pointer to a pointer to a Seln_holder. It returns an indication 
of the action which this client should take according to the standard interface. It 
also changes the addressee_rank element of that buffer to be the rank which 
is affected (the destination of a transfer, the item to be deleted, etc.), and if 
interaction with another holder is required, it stores a pointer to the appropriate 
Seln_holder element in the buffer into the location addressed by the second 
argument. Here are the details for each return value: 

SELN_IGNORE 

No action is required of this client. Another client may make a request concern¬ 
ing the selection(s) this client holds. 
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SELN_REQUEST This client is expected to request the contents of another selection and insert 

them in the location indicated by buf f er—>addressee_rank. The holder 
of the selection that should be retrieved is identified by *holder. If *holder 
points to buf f er—>secondary, the request should include 
SELN_REQ_YIELD; if it points to buf f er—>primary or 
buf f er—>secondary, the request should include 
SELN_REQ_COMMIT_PENDING_DELETE. 

Example: the called program holds the Caret and Primary selection; the I Paste I 
key went up, and there is no Secondary selection. The return value will be 
SELN_REQUEST, buf fer—>addressee_rank will be SELN_CARET and 
*holder will be the address of buf f er->shelf . The client should request 
the contents of the shelf from that holder. 

SELN_FIND This client should do a Find (if it can). Buf f er—>addressee_rank will be 
SELN_CARET; if *holder is not NULL, the target of the search is the indicated 
selection. If *holder points to buf f er->secondary, the request should 
include SELN_REQ_YIELD. 

SELN_SHELVE This client should acquire the shelf from *holder (if that is not NULL), and 
make the current contents of the primary selection (which it holds) be the con¬ 
tents of the shelf. 

SELN_DELETE This client should delete the contents of the secondary selection if it exists, or 

else the primary selection, storing those contents on the shelf. 

Buf f er—>addressee_rank indicates the selection to be deleted; *holder 
indicates the current holder of the shelf, who should be asked to yield. 

Seln_secondary_exists and seln_secondary_made are predicates 
which may be of use to an application which is not using 
seln_f igure_response (). Each takes a Seln_function_buf fer 
and returns TRUE or FALSE. When the user has made a secondary selection and 
then cancelled it, seln_secondary_made will yield TRUE while 
seln_secondary_exists will yield FALSE. This indicates the function- 
key action should be ignored. 

Callback Procedures: The client’s reply_proc() callback procedure is called when another application 

Replying to Requests makes a request concerning a selection held by this client. It is invoked once for 

each attribute in the request, plus once for a terminating attribute supplied by the 
selection library. The relevant declarations are: 
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typedef struct { 
char 

Seln_rank 

char 

char 

char 

} Seln_replier 


*client_data; 

rank; 

*context; 

* * reque s t_pointe r; 
**response_pointer; 
data; 


Seln_result 

reply_j?roc(item, context, length) 
caddr_t item; 

Seln_replier__data *context; 
int length; 


reply_proc () will be called with each of the attributes of the request in turn, 
item is the attribute to be responded to; context points to data which may be 
needed to compute the response, and length is the number of bytes remaining 
in the buffer for the response. reply_proc () should write any appropriate 
response/value for the given attribute into the buffer indicated in 
context->response_pointer, and return. 

The fields of *context contain, in order: 

□ the 32 bits of private client data passed as the last argument to 
seln_create (), returned for the client’s convenience; 

□ the rank of the selection this request is concerned with; 

n a holder for 32 more bits of context for the replier’s convenience (this will 

typically hold a pointer to data which allows a client to maintain state while 
generating a multi-buffer response); 

□ a pointer to a pointer into the request buffer, just after the current item (so 
that the replier may read the value of this item if relevant). This pointer 
should not be modified by reply_proc. 

□ a pointer to a pointer into the response buffer, where the value / response (if 
any) for this item should be stored. This pointer should be updated to point 
past the end of the response stored. (Note that items and responses should 
always be multiples of full-words; thus, this pointer should be left at an 
address which is 0 mod 4.) 

After storing the response to one item, reply_proc should return 
SELN_SUCCESS and await the next call. When all attributes in a request have 
been responded to, reply_proc will be called one more time with item == 
SELN_REQ_END_REQUEST, to give it a chance to clean up any internal state 
associated with the request. 

Two attributes which are quite likely to be encountered in the processing of a 
request due to a function-key event, SELN_REQ_C0MMIT_PENDING_DELETE 
and SELN_REQ_YIELD, are concerned more with the proper handling of secon¬ 
dary selections (rather than the needs of the requesting application), so they are 
discussed here. 
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SELN_REQ_COMMIT_PENDING_DELETE indicates that a secondary selection 
which was made in pending-delete mode should now be deleted. If the recipient 
does not hold the secondary selection, or the secondary selection is not in 
pending-delete mode, the replier should ignore the request, i.e., simply return 
SELN_SUCCESS and await the next call. SELN_REQ_YIELD, with an argu¬ 
ment of SELN_SECONDARY, means the secondary selection should be 
deselected, if it still exists. 

Complications on this basic model will now be addressed in order of increasing 
complexity. 

If the request concerns a selection the application does not currently hold, 
reply__proc should return SELN_DIDNT_HAVE immediately; it will not be 
called further for that request. 

If the request contains an item the client isn’t prepared to deal with, 
reply_proc should return SELN_UNRECOGNIZED immediately; the selec¬ 
tion library will take care of manipulating the response buffer to have the stan¬ 
dard unrecognized-format, and call back to reply_proc with the next item in 
the list. 

Finally, a response to a request may be larger than the space remaining in the 
buffer — or larger than several buffers, for that matter. This situation will never 
arise on items whose response is a single word — the selection library ensures 
there is room for at least one 4-byte response in the buffer before calling 
reply_proc. 

If a response is too big for the current buffer, the replier should store as much as 
fits in length bytes, save sufficient information to pick up where it left off in 
some persistent location, store the address of that information in 
context—>context, and return SELN_CONTINUED. Note that the replier’s 
context information should not be local to reply_proc, since that procedure 
will exit and be called again before the information is needed. 

The selection library will ship the filled buffer to the requester, and prepare a new 
one for the continuation of the response. It will then call reply_proc again, 
with the same item and context, and length indicating the space available in 
the new buffer. reply_proc () should be able to determine from 
co ntext-> context that it has already started this response, and where to 
continue from. It continues by storing as much of the remainder of the response 
as fits into the buffer, updating context—>response_pointer (and its 
own context information), and again returning SELN_CONTINUED if the 
response is not completed. When the end of the response has been stored, includ¬ 
ing any terminator if one is required, the private context information may be 
freed, and reply_proc should return SELN_SUCCESS. 

The next call to reply_proc will be to respond to the next item in the request 
if there is one, or else to SELN_REQ_END REQUEST. 
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9.6. Debugging and 
Administrative 
Facilities 


9.7. Other Suggestions 


If You Die 


A number of aids to debugging have been included in the system for applications 
which use the Selection Service. In addition to providing information on how to 
access holders of selections and maintaining the state of the user-interface keys, 
the service will respond to requests to display traces of these requests, and to 
dump its internal state on an output stream. Seln_debug is used to turn service 
tracing on or off; seln_dump instructs the service to dump all or part of its 
state on stderr. 

A number of library procedures provide formatted dumps of Selection Service 
structs and enumerated types. These can be found below as seln_dump_*. 

In debugging an application which uses the Selection Service, it may be con¬ 
venient to use a separate version of the service whose state is affected only by the 
application under test. This is done by starting the service with the -d flag; that 
is, by entering /usr/bin/selection_svc -d & to a shell. The resulting 
service will use a different RPC program number from the standard version, but 
be otherwise identical. The two versions of the service may be running at the 
same time, each responding to its own clients. A client may elect (via 
seln_use_test_service ()) to talk to the test service. Thus, it is easy to 
arrange to have an application under development talking to its own service, 
while running under a debugger which is talking to a standard service — this 
keeps the debugger, editors, etc. from interfering with the state maintained by the 
test service. 

The Selection Service depends heavily on remote procedure calls, using Sun’s 
RPC library. It is always possible that the called program has terminated or is 
not responding for some other reason; this is often detected by a timeout. The 
standard timeout at this writing is 10 seconds; this is a compromise between 
allowing for legitimate delays on loaded systems, and minimizing lockups when 
the called program really won’t respond. The delay may be adjusted by a call to 
seln_use_timeout. 

Always call seln_f igure_response () to determine what to do with a 
request 

Use seln_report_event () instead of seln_inform () to report events 
you aren’t interested in. Note that the canvas subwindow by default does not 
report SunView function-key transitions; it relies on the events falling through to 
the frame or root window, which does report the transitions. 

If you expect to I Paste I the selection, you must acquire the Caret beforehand. 

If your application dies, if it holds the shelf then you should save its contents by 
writing them to a file and calling seln_hold_f ile (). You should also yield 
the primary and secondary selections. 
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9.8. Reference Section 


Required Header Files 


Enumerated Types 


Other Data Definitions 


The reference material which follows presents first the header files and the public 
data definitions they contain; then it lists each public procedure in the selection 
library (in alphabetical order) with its formal parameter declarations, return 
value, and a brief description of its effect. 

#include <sunwindow/attr.h> 

♦include <suntool/selection_svc.h> 

♦include <suntool/selection attributes.h> 


typedef enum { 

SELN_FAILED, SELN_SUCCESS, /* basic uses */ 

SELN_NON_EXIST, SELN__DIDNT_HAVE, /* special cases */ 
S E LN_WRONG_RANK, SELN_CONTINUED, 

S E LN_CANCE L, SELN_UNRECOGNIZED 

} Seln__result ; 

typedef enum { 

SELN_UNKNOWN, SELN_CARET, SELNJPRIMARY, 

SELN_SECONDARY, SELN_SHELF, SELN_UNSPECIFIED 
} Seln_rank; 

typedef enum { 

SELN_FN__ERROR, 

S E LN__FN_S T OP , S E LN_FN_AG A IN, 

SELNJFN_PROPS, S E LN_FN_UND 0, 

S E LN_FN__F RONT, SELN_FN_PUT, 

SELN__FN_OPEN, S E LN__FN_GE T, 

SELN__FN_F IND, SELN_FN_DELETE 
} Seln_function; 

typedef enum { 

SELN_NONE, SELN_EXISTS, SELN__FILE 
} Seln_state; 

typedef enum { 

SELN_IGNORE, S E LN_REQUE ST, SELN_FIND, 

SELN__S HELVE, SELN__DELETE 
} Seln_response; 


typedef char *Seln_client; 

typedef struct { 

Seln_rank rank; 

Seln_state state; 

Seln_access access; 

} Seln holder; 


Seln holder 
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typedef struct { 
Seln__holder 
Seln_holder 
Seln__holder 
Seln__holder 

} Seln holders all 


caret; 

primary; 

secondary 

shelf; 


typedef struct { 
Seln_f unction 
Seln_rank 
Seln_holder 
Seln_holder 
Seln_holder 
Seln holder 


function; 

addressee_rank; 

caret; 

primary; 

secondary; 

shelf; 


} 


Seln function buffer; 


typedef struct 
char 

Seln__rank 

char 

char 

char 


*client_data; 

rank; 

^context; 

**request_jpointer; 

**response_pointer; 


} Seln_replier_data; 


typedef struct { 

Seln_result (^consume)(); 

char ^context; 

} Seln__requester; 


♦define SELN__BUFSIZE 

(1500 - sizeof(Seln_replier_data *) 

- sizeof(Seln_requester) 

- sizeof(char *) 

- sizeof (Seln__rank) 

- sizeof (Seln__result) 

- sizeof(unsigned)) 


typedef struct { 

Seln_replier_data 

Seln_requester 

char 

Seln_rank 

Seln_result 

unsigned 

char 

} Seln_request; 


*replier; 

requester; 

^addressee; 

rank; 

status; 

buf_size; 

data[SELN BUFSIZE]; 


\ 

\ 

\ 

\ 

\ 

\ 
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Procedure Declarations 


Seln_rank 

seln_acquire(client, asked) 


Seln_client client; 
Seln rank asked; 


client is the opaque handle returned from seln_create (); the client uses 
this call to become the new holder of the selection of rank asked, asked 
should be one of SELN_CARET, SELN_PRIMARY, SELN_SECONDARY, 
orSELN_SHELF, SELNJJNSPECIFIED. If successful, the rank actually 
acquired is returned. 

If asked is SELN_UNSPECIFIED, the client indicates it wants whichever of 
the primary or secondary selections is appropriate given the current state of the 
function keys; the one acquired can be determined from the return value. 

/* VARARGS */ 

Seln_request * 

seln_ask(holder, <attributes>, ... 0) 

Seln_holder *holder; 

Attr_union attribute; 

seln_ask () looks and acts very much like seln_query (); the only differ¬ 
ence is that it does not use a callback proc, and so cannot handle replies that 
require more than a single buffer. If it receives such a long reply, it returns the 
first buffer, and discards all that follow. The return value is a pointer to a static 
buffer; in case of error, this will be a valid pointer to a null buffer 
(buffer— >status = SELN_FAILED). seln_ask() is provided as a 
slightly simpler interface for applications that refuse to process long replies. 

void 

seln_clear_functions() 

The Selection Service is told to forget about any function keys it thinks are 
down, resetting its state to all-up. If it knows of a current secondary selection, 
the service will tell its holder to yield. 

Seln_client 

seln_create(function_proc, reply_proc, client_data) 
void (*function_proc) (); 

void (*reply_proc) (); 

caddr_t client_data); 

The selection library is initialized for this client. If this is the first client in its 
process, an RPC socket is established and the notifier set to recognize incoming 
calls. Client data is a 32-bit opaque client value which the Selection Service 
will pass back in callback procs, as described above. The first two arguments are 
addresses of client procedures which will be called from the selection library 
when client processing is required. These occasions are: 
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□ when the service sees a function-key transition which may interest this 
client, and 

□ when another process wishes to make a request concerning the selection this 
client holds, 

Details of these procedures are described under Callback Procs, above. 

/* VARARGS */ 

Seln_result 

seln_debug(<attributes> ... 0) 

Seln_attribute attribute; 

A debugging routine which requests the service to turn tracing on or off for 
specified calls. Each attribute identifies a particular call; its value should be 1 if 
that call is to be traced, 0 if tracing is to be stopped. The attributes are listed with 
other request-attributes in the first appendix. Tracing is initially off for all calls. 
When tracing is on, the Selection Service process prints a message on its 
stderr (typically the console) when it enters and leaves the indicated routine. 

void 

seln_destroy(client) 

Seln_client client; 

A client created by seln_create is destroyed: any selection it may hold is 
released and various pieces of data associated with the selection mechanism are 
freed. If this is the last client in this process using the Selection Service the RPC 
socket is closed and its notification removed. 

Seln_result 

seln_done(client, rank) 

Seln_client client; 

Seln_rank rank; 

Client indicates it is no longer the holder of the selection of the indicated rank. 
The only cause of failure is absence of the Selection Service. It is not necessary 
for a client to call this procedure when it has been asked by another client to 
yield a selection; the service will be completely updated by the acquiring client. 

void 

seln_dump_function_buffer(stream, ptr) 

FILE *stream; 

Seln_function_buffer *ptr; 

A debugging routine which prints a formatted display of a 
Seln_f unct ion_buf f er struct on the indicated stream. 
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void 

seln_dump__function_key (stream, ptr) 


FILE 


^stream; 


Seln_function *pt r; 

A debugging routine which prints a formatted display of a 
Seln_f unction_key transition on the indicated stream. 

void 

seln_dump_holder(stream, ptr) 

FILE *stream; 

Seln_holder *ptr; 

A debugging routine which prints a formatted display of a Seln_holder struct 
on the indicated stream. 

void 

seln_dump_rank (stream, ptr) 

FILE ^stream; 

Seln__rank *ptr; 

A debugging routine which prints a formatted display of a Selnjrank value on 
the indicated stream. 

void 

seln_dump__response (stream, ptr) 

FILE ^stream; 

Seln_response *ptr; 

A debugging routine which prints a formatted display of a Seln_response 
value on the indicated stream. 

void 

seln_dump_result (stream, ptr) 

FILE ^stream; 

Seln__result *ptr; 

A debugging routine which prints a formatted display of a Seln__result value 
on the indicated stream. 

void 

seln_dump_service(rank) 

Seln_rank rank; 

A debugging routine which requests the service to print a formatted display of its 
internal state on its standard error stream. Rank determines which selection 
holder is to be dumped; if it is SELN_UNSPECIFIED, all four are printed. In 
any case, the dump concludes with the state of the function keys and the set of 
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open file descriptors in the service. 


void 

seln_dump_state(stream, ptr) 


FILE 

Seln state 


^stream; 
*ptr ; 


A debugging routine which prints a formatted display of a Seln_state value 
on the indicated stream. 

Seln_response 

seln__figure_response (buffer, holder) 

Seln_function_buffer ^buffer; 

Selnjiolder **holder; 

A procedure to determine the correct response according to the standard user 
interface when seln_inf orm () returns *buf f er, or the client’s 
function_proc is called with it. The field addressee_rank will be modified 
to indicate the selection which should be affected by this client; holder will be 
set to point to the element of *buf f er which should be contacted in the ensuing 
action, and the return value indicates what that action should be. 

Seln_result 

seln_functions_state(buffer) 

Seln_functions__state *buffer; 

The service is requested to dump the state it is maintaining for the function keys 
into the bit array addressed by buff er. At present, the only commitment made 
to representation in the buffer is that some bit will be on (== 1) for each function 
key which is currently down. Thus this call can be used to determine whether 
any function keys are down, but not which. SELNSUCCESS is returned unless 
the service could not be contacted. 

int 

seln_get__function_state (which) 

Seln_f unction which; 

A predicate which returns TRUE when the service’s state shows the function key 
indicated by which is down and FALSE otherwise. 

Seln_result 

seln_hold__file (rank, path) 

Seln_rank rank; 

char *path; 

The Selection Service is requested to act as the holder of the specified rank, 
whose ASCII contents have been written to the file indicated by path. This 
allows a selection to persist longer than the application which made it can 
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maintain it Most commonly, this will be done by a process which holds the 
shelf when it is about to terminate. 


int 

seln_holder_same_client(holder, client_data) 

Seln_holder *holder; 

char *client_data; 

A predicate which returns TRUE if the holder referred to by holder is the same 
selection client as the one which provided client_data as its last argument to 
seln create. 


int 

seln_holder_same_j?rocess (holder) 
Seln holder *holder; 


A predicate which returns TRUE if the holder is a selection client in the same 
process as the caller. (This procedure is used to short-circuit RPC calls with 
direct calls in the same address space.) 


Seln_function_buffer 
seln_inform(client, 
Seln_client 
Seln_function 
int 


which, down) 
client; 
which; 
down; 


This is the low-level, policy-independent procedure for informing the Selection 
Service that a function key has changed state. Most clients will prefer to use the 
higher-level procedure seln_report_event (), which handles much of the 
standard interpretation required. 

Client is the client handle returned from seln_create (); it may be 0 if the 
client guarantees it will never need to respond to the function transition. Which 
is an element of the Seln_f unction enum defined in 
<suntool/selection_svc. h>; down is a boolean which is TRUE if the 
key went down. 

On an up-event which leaves all keys up, the service informs the holders of all 
selections of the transition, and what other parties are affected. If the caller of 
seln_inf orm () is one of these holders, its notification is returned as the 
value of the function; other notifications go out as a call on the client’s 
function_proc callback procedure (described above under Callback Procedures). 
Only one notification is sent to any single client. If the caller does not hold any 
selection, or if the transition was not an up which left all function keys up, the 
return value will be a null Seln_f unction_buf f er; buffer. rank will 
be SELN UNKNOWN. 
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/* VARARGS */ 
void 

seln_init_request(buffer, holder, <attributes>, ... 0) 


Seln_request 

Seln_holder 

char 


*buffer; 
*holder; 
*attributes; 


This procedure is used to initialize a buffer before calling seln_request . (It 
is also called internally by seln_ask and seln_query.) It takes a pointer to 
a request buffer, a pointer to a struct referring to the selection holder to which the 
request is to be addressed, and a list of attributes which constitute the request to 
be sent. The attributes are copied into buf f er—>data, and the corresponding 
size is stored into buf f er—>buf_size. Both elements of 
requester_data are zeroed; if the caller wants to handle long requests, a 
consumer-proc and context pointers must be entered in these elements after 
seln_init_request returns. 

Seln_holder 
seln_inquire(rank) 

Seln_rank rank; 

A Seln_holder struct is returned, containing information which enables the 
holder of the indicated selection to be contacted. If the rank argument is 
SELN_UNSPECIFIED, the Selection Service will return access information for 
either the primary or secondary selection holder, as warranted by the state of the 
function keys it knows about; the rank element in the returned struct will indi¬ 
cate which is being returned. 

This procedure may be called without having called seln_create () first. If 
no contact between this process and the service has been established yet, it will 
be set up, and then the call will proceed as usual. In this case, return of a null 
holder struct may indicate inaccessibility of the server. 

Seln_holders_all 
seln_inquire_all() 

A Seln_holders_all struct is returned from the Selection Service; it con¬ 
sists ofaSeln holder struct for each of the four ranks. 
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Seln__result 
reader(buffer) 

Seln_request *buffer; 


/* VARARGS */ 
Seln_result 
seln_query(holder, 
Seln_holder 
Seln_result 
char 

Attr union 


reader, context, <attributes>, ... 0) 
^holder; 

(^reader) () ; 

^context; 
attribute; 


A request is transmitted to the selection holder indicated by the holder argu¬ 
ment. Consume and context are used to interpret the response, and are 
described in the next paragraph. The remainder of the arguments to 
seln_query constitute an attribute value list which is the request. (The last 
argument should be a 0 to terminate the list.) 

The procedure pointed to by consume will be called repeatedly with a pointer 
to each buffer of the reply. The value of the context argument will be avail¬ 
able in buf f er—>requester_data. context for each buffer. This item is 
not used by the selection library; it is provided for the convenience of the client. 
When the reply has been completely processed (or when the consume proc 
returns something other than SELN_SUCCESS), seln_query returns. 


void 

seln_report_event(client, event) 

Seln_client__node ^client; 

struct inputevent *event; 

#define SELN_REPORT (event) seln_report__event (0, event) 

This is a high-level procedure for informing the selection service of a function 
key transition which may affect the selection. It incorporates some of the policy 
of the standard user interface, and provides a more convenient interface to 
seln_inform(). 

Client is the client handle returned from seln_create; it may be 0 if the 
client guarantees it will not need to respond to the function transition. Event is 
a pointer to the struct inputevent which reports the transition. 
seln_report_event () generates a corresponding call to 
seln_inf orm (), and, if the returned struct is not null, passes it to the client’s 
function_proc callback procedure (described above under Callback Procedures). 

SELN_REPORT is a macro which takes just an input-event pointer, and calls 
seln_report_event with 0 as a first argument. 
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Seln__result 

seln_request(holder, buffer) 

Seln_holder ^holder; 

Seln_request ^buffer; 

Seln_request is the low-level (policy-independent) mechanism for retrieving 
information about a selection from the process which holds it. Most clients will 
access it only indirectly, through seln_ask or seln_query. 

Seln_request takes a pointer to a holder (as returned by seln_inquire), 
and a request constructed in *buf f er . The request is transmitted to the indi¬ 
cated selection holder, and the buffer rewritten with its response. Failures in the 
RPC mechanism will cause a SELN_FAILED return; if the process of the 
addressed holder is no longer active, the return value will be 
SELN__NON__EXIST. 

Clients which call seln_request directly will find it most convenient to ini¬ 
tialize the buffer by a call to seln__init_request. 

Request attributes which are not recognized by the selection holder will be 
returned as the value of the attribute SELN_UNRECOGNIZED. Responses 
should be provided in the order requests were encountered. 


int 

seln_same_holder(holder1, holder2) 

Seln_holder *holderl, *holder2; 

This predicate returns TRUE if holder 1 and holder 2 refer to the same selec¬ 
tion client. 


int 

seln_secondary_exists(buffer) 

Seln__function_buf fer *buf fer; 

This predicate returns TRUE if the function buffer indicates that a secondary 
selection existed at the time the function key went up. 


int 

seln_secondary_made(buffer) 

Seln_function_buffer *buffer; 

This predicate returns TRUE if the function buffer indicates that a secondary 
selection was made some time since the function key went down (although it 
may have been cancelled before the key went up). 


void 

seln_use__test_service () 
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The application is set to communicate with a test version of the Selection Ser¬ 
vice, rather than the standard production version. This call should be made 
before any selection client is created; this normally means before subwindows in 
the application process are created. 

void 

seln_use_timeout(seconds) 
int seconds; 

The default timeout on subsequent RPC calls from this process is changed to be 
seconds long. 

void 

seln_yield_all() 

This procedure inquires the holders of all selection, and for each which is held by 
a client in the calling process, sends a yield request to that client and a Done to 
the service. It should be called by applications which are about to exit, or to 
undertake lengthy computations during which they will be unable to respond to 
requests concerning selections they hold. 
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9.9. Common Request 
Attributes 


The following is an annotated listing of 
<suntool/selection attributes.h>. 


/* @(#)selection_attributes.h 1.10 85/09/05 */ 

fifndef suntool_selection_attributes_DEFINED 
fdefine suntool_selection_attributes_DEFINED 

/* 

* Copyright (c) 1985 by Sun Microsystems, Inc. 

*/ 

♦include <sunwindow/attr.h> 

/* 

* Common requests a client may send to a selection-holder 
*/ 

fdefine ATTR_PKG_SELECTION ATTR_PKG_SELN_BASE 

fdefine SELN_ATTR(type, n) ATTR(ATTR_PKG_SELECTION, type, n) 

fdefine SELN_ATTR_LIST (list__type, type, n) \ 

ATTR(ATTR_PKG_SELECTION, ATTR_LIST_INLINE(list_type, type), n) 
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/* 

* Attributes of selections 

*/ 


typedef enum { 

/* Simple attributes 
*/ 

SELN_REQ_BYTESIZE = SELN_ATTR (ATTR_INT, D r 

/* value is an int giving the number of bytes in the 

* selection's ascii contents */ 

S E LN_REQ_CONT ENT S_AS C11 = SELN_ATTR_LIST(ATTR_NULL, ATTR_CHAR, 2), 

/* value is a null-terminated list of 4-byte words containing 

* the selection's ascii contents. The last word containing 

* a character of the selection should be followed by a 

* terminator word whose value is 0. If the last word of 

* contents is not full, it should be padded out with NULs */ 


SELN_REQ_CONTENTS_PIECES = SELN__ATTR_LIST (ATTR_NULL, ATTR_CHAR, 3), 

/* value is a null-terminated list of 4-byte words containing 

* the selection's contents described in the textsw's 

* piece-table format. */ 

S E LN_REQ_FIRS T = SELN_ATTR(ATTR_INT, 4), 

/* value is an int giving the number of bytes which precede 

* the first byte of the selection. */ 

S E LN_REQ_F IRS T_UN IT = SELN_ATTR (ATTR_INT, 5), 

/* value is an int giving the number of units of the selection's 

* current level (line, paragraph, etc.) which precede the 


* first unit of the selection. 

S E LN_REQ_L AS T = SELN_ATTR (ATTR_INT, 

/* value is an int giving the byte index of the last byte 

* of the selection. 

SELN_REQ_LAST_UNIT = SELN_ATTR (ATTR_INT, 

/* value is an int giving the unit index of the last unit 

* of the selection at its current level. 

SELN_REQ_LEVEL = SELN_ATTR(ATTR_INT, 

/* value is an int giving the current level of the selection 

* (See below for #defines of the most useful levels.) 


*/ 

6 ), 

*/ 

7 ) , 

*/ 

8 ) , 

*/ 


SELN_REQ_FILE_NAME = SELN_ATTR_LIST (ATTR__NULL, ATTR__CHAR, 9), 

/* value is a null-terminated list of 4-byte words containing 

* the name of the file which holds the selection (when the 

* Selection Service has been asked to hold a selection). 

* The string is represented exactly like ascii contents. */ 
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/* Simple commands (no parameters) 

*/ 

S E LN_RE Q_COMMIT_P ENDING_DE LETE 

= SELN__ATTR (ATTR_N0_VALUE, 65), 

/* There is no value. The replier is instructed to delete any 

* secondary selection made in pending delete mode. */ 

SELN_REQJDELETE = S E LN_AT T R(ATTR_N0_VALUE, 66), 

/* There is no value. The replier is instructed to delete the 

* selection referred to in this request. */ 

SELN_REQ_RESTORE = SELN__ATTR (ATTR_N0__VALUE, 67), 

/* There is no value. The replier is instructed to restore the 

* selection referred to in this request, if it has maintained 

* sufficient information to do so. */ 


/* Other commands 
*/ 


SELN_REQ_YIELD = SELN_ATTR (ATTR_ENUM, 97), 

/* The value in the request is not meaningful; in the response, 
the value is a Seln_result which is the replier's 
return code. The replier is requested to yield the 
selection referred to in this request. SELN_SUCCESS, 

SELN_DIDNT_HAVE, and SELN_WRONG_RANK are legitimate 
responses (the latter comes from a holder asked to 
yield the primary selection when it knows a function-key 
is down). */ 

SELN_REQ_FAKE_LEVEL = SELN_ATTR (ATTR_INT, 98), 

/* value is an int giving a level to which the selection 

should be expanded before processing the remainder of 
this request. The original level should be maintained 
on the display, however, and restored as the true level 
on completion of the request */ 

SELN_REQ__SET_LEVEL = SELN_ATTR (ATTR_INT, 99), 

value is an int giving a level to which the selection 

should be set. This request should affect the true level */ 


/* 

★ 


/* Service debugging commands 
*/ 

S E LN_T RACE_ACQU I RE = SELN__ATTR (ATTR_BOOLEAN, 193), 

SELN_TRACE_DONE = SELN_ATTR(ATTR_BOOLEAN, 194), 

S E LN_T RACE_HO LD__F I LE = SELN_ATTR (ATTR_BOOLEAN, 195), 

SELN_TRACE__INFORM = SELN__ATTR (ATTR_BOOLEAN, 19 6), 

SELN_TRACE_INQUIRE = SELN__ATTR (ATTR_BOOLEAN, 197), 

S E LN_T RACE_YIELD = SELN_ATTR(ATTR_BOOLEAN, 198), 

SELN_TRACE_STOP = SELN_ATTR(ATTR_BOOLEAN, 199), 

/* value is a boolean (TRUE / FALSE) indicating whether calls 

* to that procedure in the service should be traced. 

* TRACE_INQUIRE also controls tracing on seln_inquire all(). */ 

SELN_TRACE_DUMP = SELN_ATTR (ATTR_ENUM, ~ 200), 

/* value is a Seln_rank, indicating which selection holder 


should be dumped; SELN_UNSPECIFIED indicates all holders. */ 
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/* Close bracket so replier can terminate commands 
* like FAKE_LEVEL which have scope 
*/ 

SELN_REQ_END_REQUEST = SELN_ATTR (ATTR_NO_VALUE, 

/* Error returnd for failed or unrecognized requests 
*/ 

SELN_REQ_UNKNOWN = SELN_ATTR (ATTRJENT, 

S E LN_RE Q_F AI LED = SELN__ATTR (ATTR_INT f 


} Seln attribute; 


/* Meta-levels available for use with SELN__REQ_FAKE/SET_LE VEL. 

* SELN__LEVEL_LINE is "text line bounded by newline characters, 

* including only the terminating newline” 
*/ 

typedef enum { 


S E LN_LE VE L__F IRS T 
SELN_LEVEL_LINE 
S E LN_LE VE L_AL L 
SELN_LEVEL_NEXT 
S E LN_LE VE L_P RE VIOU S 
} Seln_level; 

#endif 


0x40000001, 

0x40000101, 

0x40008001, 

0x4000F001, 

0x4000F002 


253), 


254) , 

255) 
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9.10. Two Program 
Examples 


There are several programs in the SunView 1 Programmer* s Guide that do a 
seln_ask () for the primary selection. Here are two sample programs that 
manipulate the selection in more complex ways. 


get_selection Code The following code is from the program get_s election, which is part of the 

release. This program copies the contents of the desired SunView selection to 
stdout. For more information, consult the get__select ion(l) man page. 

#ifndef lint 

static char sccsid[] = (#)get_selection.c 10.5 86/05/14"; 

#endif 

/* 

* Copyright (c) 1986 by Sun Microsystems, Inc. 

*/ 


#include <stdio.h> 

#include <sys/types.h> 

#include <suntool/selection_svc.h> 
#include <suntool/selection_attributes.h> 

static Seln__result read_proc(); 

static int data read = 0; 


static void 


quit () ; 


#ifdef STANDALONE 
main(argc, argv) 

#else 

get__selection_main (argc 
#endif STANDALONE 
int 
char 

{ 

Seln_client 

Seln_holder 

Seln_rank 

char 

int 


argv) 

argc; 

**argv; 

client; 

holder; 

rank = S E LN_P RIMARY; 
context = 0; 
debugging = FALSE; 


while (—argc) { 

/* command-line args control rank of desired selection, 
/* use of a debugging service, and rpc timeout 
argv++; 

switch (**argv) { 
case '1' : 

rank = S E LN_P RIMARY; 
break; 
case '2' : 

rank = S E LN_S E CONDARY; 


*/ 

*/ 
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break; 
case '3': 

rank = SELN__SHELF; 
break; 
case 'D': 

seln_use_test_service () ; 
break; 
case 't': 
case 'T': 

seln__use_timeout (atoi (++argv) ) ; 

—argc; 
break; 
default: 

quit("Usage: get_selection [D] [t seconds] [1 I 2 |3]\n"); 

} 

} 

/* find holder of desired selection */ 
holder = seln__inquire (rank) ; 
if (holder, state — SELN__NONE) { 

quit("Selection non-existent, or selection-service failure\n"); 

} 

/* ask for contents, and let callback proc print them */ 

(void) seln_query(&holder, read_proc, &context, 

SELN__REQ_CONTENTS_ASCI 1, 0, 0); 


if (data__read) 
exit (0); 

else 

exit (1); 

} 

static void 
quit(str) 

char *str; 

{ 

fprintf(stderr, str); 
exit(1); 

> 

/* 

* Procedure called with each buffer of data returned in response 

* to request transmitted by seln_query. 

*/ 

static Seln_result 
read_proc(buffer) 

Seln_request ^buffer; 

{ 

char *reply; 

/* on first buffer, we have to skip the request attribute, 

* and then make sure we don't repeat on subsequent buffers 
*/ 
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if (*buffer->requester.context == 0) { 

if (buffer == (Seln_request *) NULL || 


*((Seln_attribute *) buffer->data) != SELN_REQ_CONTENTS_ASC11) { 
quit("Selection holder error — unrecognized request\n"); 


reply = buffer->data + sizeof (Seln_attribute); 
*buffer->requester.context = 1; 

} else { 

reply = buffer->data; 

} 

fputs(reply, stdout); 
fflush(stdout); 
data__read = 1; 
return SELN_SUCCESS; 
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seln demo 


Large Selections 


The following program, seln demo gets the selection, but it also sets the selec¬ 
tion and responds to appropriate queries about it. It isn’t an entirely realistic pro¬ 
gram, since it doesn’t provide selection feedback or use function keys. 

It displays a panel with several choices and buttons and a text item. You choose 
the rank of the selection you wish to set or retrieve first. If you are setting the 
selection, you may also choose whether you want to literally set the selection or 
provide the name of a file which contains the selection. Then either type in the 
selection and push the Set button, or just push the Get button to retrieve the 
current selection of the type you chose. 

The code has three logical sections: the procedures to create and service the 
panel, the code to set a selection, and the code to get a selection. The routines to 
set and get the selection are complicated because they are written to allow arbi¬ 
trary length selections. Try selecting a 3000 byte piece of text; although you can 
only see 10 characters of it in the text panel item, the entire selection can be 
retrieved and/or set. 

In order to handle large selections, the selection service breaks them into smaller 
chunks of about 2000 bytes called buffers. The routines you write must be able 
to handle a buffer and save enough information so that when they are called 
again with the next buffer, they can pick up where they left off. seln_demo uses 
the context fields provided in the Selection Service data structures to accomplish 
this. 
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#ifndef lint 

static char sccsid[] = (#)seln_demo.c 1.5 88/03/14 Copyr 1986 Sun Micro"; 

#endif 

/* 

* selnjiemo. c 

★ 

* demonstrate how to use the selection service library 
*/ 


#include <stdio.h> 

#include <suntool/sunview.h> 
#include <suntool/panel.h> 
#include <suntool/seln.h> 

static Frame frame; 
static Panel panel; 

int err =0; 

char *malloc(); 

/* 

* definitions for the panel 
*/ 


static Panel_item text__item, type_item, source_item, mesg_item; 
static Panel__item set_item[3], get_item[3]; 

static void set__button_proc () , get button ^p roc () , change label_proc () ; 


#define PRIMARY_CHOICE 0 

#define SECONDARY__CHOICE 1 

tdefine SHELF_CHOICE 2 

#define ITEM_CHOICE 0 

#define FROMFILE CHOICE 1 


int selection_type = PRIMARY_CHOICE; 
int selection_source = ITEM CHOICE; 


/* get/set the primary selection */ 

/* get/set the secondary selection */ 

/* get/set the shelf */ 

/* use the text item literally as the 
selection */ 

/* use the text item as the name of a 
file which contains the selection */ 


char *text_labels[3][2] = { 

{ " 

"New primary selection 

"File containing new primary selection:" 

}, 

{ 

"New secondary selection 

"File containing new secondary selection: 

}, 

{ 

"New shelf:" f 

"File containing new shelf:" 
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}; 


char *mesg__labels [3] [2] = { 
{ " 


}, 

{ 


}, 

{ 


"Type in a selection and hit the Set Selection button”, 
"Type in a filename and hit the Set Selection button" 


"Type in a selection and hit the Set Secondary button", 
"Type in a filename and hit the Set Secondary button" 


"Type in a selection and hit the Set Shelf button ”, 
"Type in a filename and hit the Set Shelf button" 


}; 

Seln_rank type_to_rank[3] = { SELN_PRIMARY, SELN_SECONDARY, SELN_SHELF }; 
/* 

* definitions for selection service handlers 
*/ 

static Seln_client s_client; /* selection client handle */ 

#define FIRST_BUFFER 0 

#define NOT FIRST BUFFER 1 


char ^selection bufs[3]; 


/* contents of each of the three selections; 
they are set only when the user hits a set 
or a get button */ 


int f unc__key_jproc () ; 
Seln__result reply_j?roc () 
Seln_result read_j>roc () ; 
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/********************************************************************/ 

/* main routine */ 

/********************************************************************/ 

main(argc, argv) 
int argc; 
char **argv; 

{ 

/* create frame first */ 

frame = window__create (NULL, FRAME, 

FRAME_ARGS, argc, argv, 

WIN_ERROR__MSG, "Cannot create frame”, 

F RAME_L ABE L, ” seln_demo", 

0 ) ; 

/* create selection service client before creating subwindows 
(since the panel package also uses selections) */ 

s_client = seln_create (func_key_j?roc, reply_j?roc, (char *) 0); 
if (s___client == NULL) { 

fprintf(stderr, "seln_demo: seln_create failed!\n”); 
exit(1); 

} 

/* now create the panel */ 

panel = window_create(frame, PANEL, 

WIN_ERROR_MSG, "Cannot create panel", 

0 ); 

init__panel (panel) ; 
window_fit_height(panel); 
window_fit_height(frame); 
window_main_loop(frame); 

/* yield any selections we have and terminate connection with the 
selection service */ 

seln__destroy (s_client) ; 

} 
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/***********************************************************************/ 

/* routines involving setting a selection */ 

/***********************************************************************/ 

/* 

* acquire the selection type specified by the current panel choices; 

* this will enable requests from other clients which want to get 

* the selection's value, which is specified by the source_item and text__item 
*/ 

static void 

set_button_jproc (/* args ignored */) 

{ 

Seln_rank ret; 

char *value = (char *) panel__get__value (text__item) ; 

if (select ion_source == FROMFILE__CHOICE) { 

/* set the selection from a file; the selection service will 
actually acquire the selection and handle all requests */ 

if (seln_hold_f ile (type_to_rank [selection__type], value) 

!= SELN_SUCCESS) { 

panel_set (mesg_item, PANEL_LABEL_STRING, 

"Could not set selection from named file!”, 0); 

err++; 

} else if (err) { 

panel_set (mesg___item, PANEL_LABEL_STRING, 

mesg_labels [selection_type] [selection_source], 0) ; 

err = 0; 

} 

return; 

) 

ret = seln_acquire (s__client, type__to_rank [ selection_type]) ; 

/* check that the selection rank we received is the one we asked for */ 

if (ret != type_to__rank [selection__type] ) { 

panel_set (mesg_item, PANEL_LABEL_STRING, 

"Could not acquire selection!", 0); 

err++; 

return; 

} 

set_selection_value(selection_type, selection_source, value); 

} 

/* 

* copy the new value of the appropriate selection into its 

* buffer so that if the user changes the text item and/or the current 

* selection type, the selection won't mysteriously change 
*/ 

set_selection_value(type, source, value) 
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int type, source; 
char *value; 

{ 

if (selection__bufs [type] != NULL) 

free(selection_bufs[type]); 
selection__buf s [type] = malloc (strlen (value) + 1) ; 
if (selection_bufs[type] == NULL) { 

panel__set (mesg_item, PANEL_LABEL__STRING, "Out of memory!", 
errH; 

} else { 


) 


strcpy (selection__bufs [type], 
if (err) { 

panel_set (mesg_item, 
err = 0; 

} 


value); 

PANEL_LABEL_STRING, 

mesg_labels[type][source]. 


0 ) ; 


0 ); 


/* 

* func_key_proc 

★ 

* called by the selection service library whenever a change in the state of 

* the function keys requires an action (for instance, put the primary 

* selection on the shelf if the user hit PUT) 

*/ 


func__key_proc (client_data, args) 
char *client_data; 

Seln_function_buffer *args; 

{ 

Seln_holder ^holder; 

/* use seln_figure_response to decide what action to take */ 


switch (seln_figure_response(args, Sholder)) { 

case SELN_IGNORE: 

/* don't do anything */ 
break; 

case SELN_REQUEST: 

/* expected to make a request */ 
break; 


case SELN_SHELVE: 

/* put the primary selection (which we should have) on the 
shelf */ 

if (seln__acquire (s_client, SELN_SHELF) != SELN_SHELF) { 
panel_set (mesg_item, PANEL_LABEL_STRING, 

"Could not acquire shelf!", 0); 

err++; 

} else { 


shelve_primary_selection(); 

} 

break; 


W sun 

\r microsystems 


Revision A, of May 9, 1988 





134 SunView 1 System Programmer’s Guide 


case SELN_FIND: 

/* do a search */ 
break; 

case SELN_DELETE: 

/* do a delete */ 
break; 



shelve_primary_selection() 


char *value = selection_bufs[PRIMARY_CHOICE]; 

if (selection_bufs [SHELF__CHOICE] != NULL) 

free (selectionjoufs [SHELF_CHOICE] ) ; 
selection_bufs[SHELF_CHOICE] = malloc(strlen(value)+1); 
if (selection_bufs[SHELF_CHOICE] == NULL) { 


panel_set (mesg_item, PANEL_LABEL_STRING, "Out of memory!", 0) ; 
err++; 


} else { 


strcpy(selection_bufs [SHELF_CHOICE] , value) ; 


/* 



* reply_j>roc 


* called by the selection service library whenever a request comes from 

* another client for one of the selections we currently hold 
*/ 

Seln_result 

reply_proc(item, context, length) 

Seln__attribute item; 

Seln_replier_data ^context; 
int length; 

{ 


int size, needed; 
char *seln, *destp; 

/* determine the rank of the request and choose the 
appropriate selection */ 

switch (context->rank) { 
case SELN PRIMARY: 


seln = selection_bufs[PRIMARY_CHOICE]; 
break; 


case SELN SECONDARY: 


seln = selection_bufs[SECONDARY_CHOICE]; 
break; 


case SELN SHELF: 



seln = selection_buf s [SHELF__CHOICE] ; 
break; 
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default: 

seln = NULL; 

} 

/* process the request */ 

switch (item) { 

case SELN_REQ_CONTENTS_ASCII: 

/* send the selection */ 

/* if context->context == NULL then we must start sending 
this selection; if it is not NULL, then the selection 
was too large to fit in one buffer and this call must 
send the next buffer; a pointer to the location to start 
sending from was stored in context->context on the 
previous call */ 

if (context->context == NULL) { 
if (seln == NULL) 

return (SELN_DIDNT__HAVE) ; 
context->context = seln; 

} 

size = strlen(context->context); 

destp = (char *)context->response_pointer; 

/* compute how much space we need: the length of the selection 
(size) , plus 4 bytes for the terminating null word, plus 0 
to 3 bytes to pad the end of the selection to a word 
boundary */ 

needed = size + 4; 
if (size % 4 != 0) 

needed += 4 - size % 4; 
if (needed <= length) { 

/* the entire selection fits */ 
strcpy(destp, context->context); 
destp += size; 

while ((int)destp % 4 != 0) { 

/* pad to a word boundary */ 

*destp++ = '\0'; 

} 

/* update selection service's pointer so it can 
determine how much data we are sending */ 
context->response_pointer = (char **)destp; 

/* terminate with a NULL word */ 
*context->response_pointer++ = 0; 
return(SELN_SUCCESS); 

} else { 

/* selection doesn't fit in a single buffer; rest 
will be put in different buffers on subsequent 
calls */ 

strncpy(destp, context->context, length); 
destp += length; 
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context->response_j?ointer = (char **)destp; 
context->context += length; 
return(SELN_CONTINUED); 

} 

case SELN_REQ_YIELD: 

/* deselect the selection we have (turn off highlight, etc.) */ 

*context->response_pointer++ = (char *)SELN_SUCCESS; 
return(SELN_SUCCESS); 
case SELN_REQ_BYTESIZE: 

/* send the length of the selection */ 

if (seln == NULL) 

return(SELN_DIDNT_HAVE) ; 

*context->response_j?ointer++ = (char *)strlen(seln); 
return(SELN_SUCCESS); 
case SELN__REQ_END_REQUEST : 

/* all attributes have been taken care of; release any 
internal storage used */ 
return(SELN_SUCCESS); 
break; 

default: 

/* unrecognized request */ 
return(SELN_UNRECOGNIZED); 

} 

/* NOTREACHED */ 
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/*******************************************************************/ 

/* routines involving getting a selection */ 

/*******************************************************************/ 

/* 

* get the value of the selection type specified by the current panel choices 

* from whichever client is currently holding it 
*/ 

static void 

get_button_proc(/* args ignored */) 

{ 

Seln__holder holder; 
int len; 

char context = FIRST__BUFFER; /* context value used when a very long 

message is received; see procedure 
comment for read_j?roc */ 

if (err) { 

panel_set (mesg_item, PANEL_LABEL_STRING, 

mesg_labels [selection_type] [selection_source], 0) ; 

err = 0; 

} 

/* determine who has the selection of the rank we want */ 

holder = seln_inquire (type_to__rank [selection_type]) ; 
if (holder.state == SELN_NONE) { 

panel__set (mesg__item, PANEL_LABEL_STRING, 

"You must make a selection first!", 0); 

err++; 

return; 

} 

/* ask for the length of the selection and then the actual 
selection; read_jproc actually reads it in */ 

(void) seln_query(&holder, read_proc, Scontext, 

S E LN__REQ_B YTE SIZ E, 0, 

SELN_REQ_CONTENTS_ASCII, 0, 

0 ); " 


/* display the selection in the panel */ 
len = strlen (selection_bufs [selection__type]) ; 

if (len > (int) panel_get (text_item, PANEL_VALUE_STORED_LENGTH) ) 
panel_set (text__item, PANEL_VALUE_STORED_LENGTH, len, 0) ; 
panel_set_value (text___item, selection_bufs [selection_type]) ; 

} 

/* 

* called by seln_query for every buffer of information received; short 
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* messages (under about 2000 bytes) will fit into one buffer; for larger 

* messages, read__proc will be called with each buffer in turn; the context 

* pointer passed to seln_query is modified by read_j?roc so that we will know 

* if this is the first buffer or not 
*/ 

Seln_result 
read_proc(buffer) 

Seln_request ^buffer; 

{ 

char *reply; /* pointer to the data in the buffer received */ 

unsigned len; /* amount of data left in the buffer */ 

int bytes_to__copy; 

static int selection_have_bytes; /* number of bytes of the selection 

which have been read; cumulative over all calls for 
the same selection (it is reset when the first 
buffer of a selection is read) */ 

static int selection_len; /* total number of bytes in the current 

selection */ 

if (*buffer->requester.context == FIRST_BUFFER) { 

/* this is the first buffer */ 


if (buffer == (Seln__request *)NULL) { 

panel_set (mesg_item, PANEL__LABEL_STRING, 

"Error reading selection - NULL buffer", 0) ; 

err++; 

return(SELNJJNRECOGNIZED); 

) 

reply = buffer->data; 
len = buffer->buf_size; 

/* read in the length of the selection */ 

if (*( (Seln_attribute *)reply) != SELN_REQ_BYTESIZE) { 

panel_set (mesg_item, PANEL__LABEL_STRING, 

"Error reading selection - unrecognized request", 

0 ); 

errH; 

return(SELNJJNRECOGNIZED); 

) 

reply += sizeof (Seln__attribute) ; 

len = buf fer->buf_size - sizeof (Seln__attribute) ; 
selection_len = Mint *) reply; 

reply += sizeof(int); /* this only works since an int is 4 

bytes; all values must be padded to 
4-byte word boundaries */ 

len -= sizeof(int); 

/* create a buffer to store the selection */ 
if (selection_bufs[selection_type] != NULL) 
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free(selection_bufs[selection_type]); 
selection_bufs[selection_type] = malloc(selection_len + 1); 
if (selection_bufs[selection_type] == NULL) { 

panel__set (mesg_item, PANEL_LABEL_STRING, 

"Out of memory!”, 0); 

err++; 

return (SELN__FAILED) ; 

} 

selection_have_bytes = 0; 

/* start reading the selection */ 

if (*(Seln_attribute *)reply != SELN_REQ_CONTENTS_ASCII) { 
panel_set (mesg_item, PANEL_LABEL_STRING, 

"Error reading selection - unrecognized request", 

0 ) ; 

errH; 

return (SELNJJNRECOGNIZED) ; 

} 

reply += sizeof(Seln_attribute); 
len -= sizeof(Seln__attribute); 

*buffer->requester.context = NOT_FIRST_BUFFER; 

) else { 

/* this is not the first buffer, so the contents of the buffer 
is just more of the selection */ 

reply = buffer->data; 
len = buf fer->buf__size; 

} 

/* copy data from the received buffer to the selection buffer 
allocated above */ 

bytes_to_copy = selection_len - selection_have_bytes; 
if (len < bytes_to_copy) 

bytes_to__copy = len; 

strncpy(&selection_bufs[selection_type][selection_have__bytes], 

reply, bytes_to_copy); 

selection_have_bytes += bytes_to_copy; 
if (selection_have_bytes == selection_len) 

selection_bufs[selection_type][selection_len] = 'Non¬ 
return (SELN_SUCCESS) ; 

} 
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/***********************************************************/ 
/* panel routines */ 

/***********************************************************/ 

/* panel initialization routine */ 


init_panel(panel) 
Panel panel; 

{ 


mesg_item = panel_create__item (panel, PANEL_MESSAGE, 

P ANE L__L AB E L_S T RING, 

mesg_labels [PRIMARY__CHOICE] [ITEM_CHOICE] , 

0 ) ; 

type_item = panel_create_item(panel, PANEL_CYCLE, 

PANEL_LABEL_STRING, "Set/Get: ", 

PANEL_CHOICE_STRINGS, "Primary Selection", 

"Secondary Selection", 
"Shelf", 


PANEL_NOTIFY_PROC, 
P ANE L_L AB E L_X, 
PANEL_LABEL__Y, 

0 ); 


0 r 

change_label__proc, 
ATTR_COL(0), 
ATTR_ROW(l), 


source_item = pane l__create_i tern (panel, PANEL__CYCLE, 

PANEL__LABEL_STRING, "Text item contains:", 

PANEL_CHOICE_STRINGS, "Selection", 

"Filename Containing Selection", 

0 , 


P AN E L__N 0 TIF Y_P ROC, change_label _proc, 

0 ); 


text__item = panel__create_item(panel, PANEL_TEXT, 


set_item[0] 


set_item[l] 


set item[2] 


PANEL_LABEL_STRING, 

text_labels [PRIMARY_CHOICE] [ ITEM__CHOICE] 
P ANE L__VALUE_D ISP L AY_LEN GT H, 2 0, 

0 ) ; 


= panel_create__item (panel, 
P ANEL_LABEL_IMAGE, 

P ANE L_NOT IF Y__P ROC, 

P ANE L_L ABE L_X , 
PANEL__LABEL_Y, 

0 ) ; 

= panel_create_item(panel, 
P ANEL_LABEL_IMAGE, 

P ANE L_N 0 TIF Y_P ROC, 

P ANE L_L AB E L__X , 

P ANE L_L ABE L__Y, 
PANEL_SHOW_ITEM, 

0 ) ; 

= panel_create_item (panel, 
P ANEL_LABEL_IMAGE, 


PANEL__BUTTON, 
panel_button__image (panel 
"Set Selection", 
set_button_j>roc, 

ATTR__COL (0) , 

ATTR_ROW(5), 

PANE L_BUT TON, 
panel_button_image(panel 
"Set Secondary", 
set_button_proc, 

ATTR__COL (0) , 

ATTR_ROW(5), 

FALSE, 

PANEL_BUTTON, 
panel_button_image(panel 
"Set Shelf", 15, 


15,0), 


15,0), 
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} 


get_item[0] 


get_item[l] 


get__item [2] 


P ANE L_NOT IF Y_P ROC, 

P ANE L_LABE L__X, 

PANE L_L ABE L__Y, 

PANE L_S HOW_ITEM, 

0 ); 

= panel_create_item (panel, 
P ANE L_JL AB E L_ I MAGE , 

PANE L_NOT IF Y_P ROC, 
PANEL_LABEL_X, 

P ANE L__L ABE L_Y, 

0 ); 

= panel_create_item (panel, 
PANE L__LABEL_ IMAGE, 

P AN E L_N 0 TIF Y_P ROC, 
PANEL_SHOW_ITEM, 

P ANE L_L ABE L_X, 

P ANE L__L AB E L_Y, 

0 ) ; 

= panel_create_item (panel, 
P ANEL_LABEL_IMAGE, 

PANE L__NOT IF Y_P ROC, 
PANEL_SHOW_ITEM, 

P ANE L_L ABE L__X, 

P ANE L_L AB E L_Y, 

0 ); 


set__button_proc, 

ATTR_COL(0) , 

ATTR_ROW(5), 

FALSE, 

PANEL_BUTTON, 
panel_button_image(panel, 

"Get Selection”, 15,0), 
get_button_proc, 

ATTR_COL(20) , 

ATTR_ROW(5), 

PANEL_BUTTON, 
panel_button_image(panel, 

"Get Secondary", 15,0), 
get_button_proc, 

FALSE, 

ATTR_COL(20) , 

ATTR_ROW(5), 

PANEL_BUTTON, 
panel_button_image(panel, 

"Get Shelf", 15,0), 
get__butt on_proc, 

FALSE, 

ATTR_COL(20) , 

ATTR_ROW(5), 


/* 

* change the label of the text item to reflect the currently chosen selection 

* type 
*/ 


static void 

change_label_j?roc(item, value, event) 

Panel_item item; 
int value; 

Event *event; 

{ 

int old_selection_type = selection_type; 

selection_type = (int)panel_get_value(type_item); 
selection_source = (int)panel_get_value(source_item); ^ 
panel_set (text_item, PANEL_LABEL_STRING, 

text_labels [selection_type] [selection__source], 0) ; 
panel_set (mesg_item, PANEL_LABEL__STRING, 

mesg_labels [selection_type] [selection_source], 0) ; 
if (old__selection_type != selection_type) { 

panel___set (set_item [old___selection_type], 

PANEL_SHOW_ITEM, FALSE, 0) ; 
panel_set (set_item[selection_type], 
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} 


PANEL_SHOW_ITEM, TRUE, 0); 
panel_set(get_item[old_selection_type], 

PANEL_SHOW_ITEM, FALSE, 0); 
panel_set(get_item[selection_type], 

PANEL SHOW ITEM, TRUE, 0); 
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The User Defaults Database 


Many UNIX programs are customizable in that the user can modify their behavior 
by setting certain parameters checked by the program at startup time. This 
approach has been extended in SunView to include facilities used by many appli¬ 
cations, such as menus, text and scrollbars, as well as applications. 

The SunView user defaults database is a centralized database for maintaining 
customization information about different programs and facilities. 

This chapter is addressed to programmers who want their programs to make use 
of the defaults database. For a discussion of the user interface to the defaults 
database, read the def aultsedit(l) manual page in the SunOS Reference 
Manual and see the section on def aultsedit in the SunView 1 Beginner’s 
Guide. 

In this chapter, customizable parameters are referred to as options-, the values 
they can be set to are referred to as values. 

All definitions necessaiy to use the defaults database may be obtained by includ¬ 
ing the file <sunwindow/def aults . h>. 

Why a Centralized Database? Traditionally, each customizable program has a corresponding customization file 

in the user’s home directory. The program reads its customization file at startup 
time to get the values the user has specified. 

Examples of customizable programs are mail(l), csh(l), and sunview(l). 

The corresponding customization files are .mailrc, . cshrc, and- 
. sunview. 

While this method of handling customization works well enough, it can become 
confusing to the user because: 

□ Since the information is scattered among programs, it’s difficult for the user 
to determine what options she or he can set. 

□ Since the format of each customization file is different, the user must find 
and read documentation for each program he or she wants to customize. 

□ Even after the user has located the customization file and become familiar 
with its format, it’s often difficult for the user to determine what the legal 
values are for a particular option. 
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10.1. Overview 


Master Database Files 


Private Database Files 


SunView addresses these problems by providing a centralized database which 
can be used by any customizable program. The user can view and modify the 
options in the defaults database with the interactive program 
defaultsedit(l). 

The defaults database actually consists of a single master database and a private 
database for each user. 

The master database contains all the options for each program which uses the 
defaults database. For each option, the default value is given. 

The user’s private database contains the values she or he has specified using 
def aultsedit. An option’s value in the private database takes precedence 
over the option’s default value in the master database. 

Application programs retrieve values from the database using the routines 
described later in this chapter. These routines first search the user’s private data¬ 
base for the value. If the value is not found in the private database, then the 
default value from the master database is returned. Each of these routines 
specify a fall-back default value which is used if neither database contains the 
value. It should match the value in the master database. 

The master database is stored in the directory /usr/lib/defaults as a 
number of individual files, each containing the options for one program or pack¬ 
age. These files are created with a text editor by the author of the program or 
package; see Section 10.3, Creating a . d File: Example , later in this chapter. 
By convention, the file name is the capitalized name of the program or package, 
with the suffix . d — Mail. d, SunView. d, Menu . d, etc. 

The defaults database itself has two options you can set using def aultsedit 
to control where the master database resides: 

□ Directory is provided so that a group may have its own master database 
directory in which to do development independently of the standard 
/usr/lib/defaults directory. 

□ Private Directory is provided so that an individual developer may have his 
own private master database for development. Note that this directory must 
have copies (or symbolic links) to all of the . d files in 
/usr/lib/def aults, or accesses to the absent files will result in run¬ 
time errors. 

When the master database is accessed, the defaults routines look for the appropri¬ 
ate . d file first in the Private directory (if specified). If the file is not found or 
the directory not specified, then if a Directory is specified it is searched, other¬ 
wise the default directory, /usr/lib/def aults, is searched. 

A user’s private database is stored in the file .defaults in the user’s home 
directory. This is where changes the user makes using def aultsedit are 
recorded. 23 


23 There is rarely any need for the user to edit his .defaults file by hand — it is automatically created 
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10.2. File Format 


Option Names 


There is an option called Private_only which allows the user to disable the read¬ 
ing of the master database entirely, thereby reducing program startup time. Note 
that for this to work, you must make sure that the fall-back values you specify in 
your program exactly match the values in the master database. 

The format for both master and private database files is identical. 

The first line in the file contains a version number. 24 The rest of the file consists 
of a number of lines, each line contains either an option name with its associated 
value or a comment, preceded by a semi-colon (;). Blank lines are also legal. 

The option names are organized hierarchically, just like files in a file system. 
Names must always start with a slash character, (/), and each level in the naming 
hierarchy is separated from the previous level by a slash character. Each name 
consists of one or more letters (A-Z, a-z), digits (0-9), dollar signs ($), and under¬ 
scores (_). By convention, the first letter of each name is capitalized. 25 

There are two shorthand notations for option names. First, whenever a line does 
not start with a slash, the previous node is prepended to the name (this is similar 
to the treatment of path names in UNIX). So 

/SunView/Font 
$Help 

is equivalent to 

/SunView/Font 
/SunView/Font/$Help 

The second shorthand convention is that any time two slashes in a row are 
encountered, the option name previously defined at that level is assumed. Each 
pair of slashes corresponds to one name. So 

/SunView/Font 
//Walking_Menus 
//Icon_gravity 

is equivalent to 

/SunView/Font 
/SunView/Walking_Menus 

/SunView/Icon_gravity 


and updated by default sedit. The one time the user needs to edit his . de fau It s file by hand is to 
disable the defaults Testmode option once it has been enabled. See the discussion in Section 10.7, Error 
Handling, below. 

24 The version number is included so that if any incompatible changes are made to the default database 
format in the future, the library routines can tell when they encounter an older file format. 

25 This convention is just for readability — internally all names are converted to lower case, so the defaults 
database is insensitive to case. 
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and 

/SunView/Font/Bold 

///Italic 

///Size 

is equivalent to 

/SunView/Font/Bold 
/SunView/Font/Italic 

/SunView/Font/Size 


Option Values All option values are stored as strings. They have the same syntax as quoted 

strings in C. In particular, the backslash character (\) is used as an escape charac¬ 
ter for inserting other characters into the quoted string. The following backslash 
escapes are recognized: 

Table 10-1 Defaults Metacharacters 


Backslash Escape 

Prints as: 

\\ 

Backslash 

\" 

Double quote 

V 

Single quote 

\n 

Newline 

\t 

Tab 

\b 

Backspace 

\r 

Carriage return 

\f 

Form feed 

\ddd 

3 digit octal number specifying a single character 


Option values can be up to 10,000 characters long. 


Distinguished Names There are several distinguished names used by def ault sedit. See the next 

section for an example illustrating their usage. 

$ He lp $ Help allows you to add an explanatory string to be displayed by 

def ault sedit for each option. 

$Enumeration An enumerated option is one in which the values are explicitly given, such as 

{True, False}, {Yes, No}, {North, South, East, West} etc. 26 The user selects one 
of the values using def ault sedit. 

The way that def ault sedit knows that it has encountered an enumerated 
option is by the level name $Enumerat ion. The values for the enumerated 
option follow at the same level. Note that you can specify a help string for the 
entire enumerated option, as well as specifying the value. 


26 There is no limit to the number of values an enumerated option can have. 
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$Message 


10.3. Creating a 
Example 


$Message allows you to add a one-line message to be displayed by 
defaultsedit. Use this to make more readable the display of a category 
with many options by setting off related options with blank lines or headings. 


. d File: Adding options for a new program to the database corresponds to adding a new 

first-level option name in the master database, and appears to the user as a new 
category in defaultsedit. You do this by creating the appropriate . d file in 
/usr/lib/defaults. If the file is in the correct format, and ends in .d, 
then defaultsedit will automatically display it as a new category. 

Let’s create such a file for a game called “Space Wars.” The options are: the 
number of friendly and enemy ships, whether or not stars attract ships, the name 
of the user’s ship, and the direction that ships enter the window from. 

To conform to the naming convention for master database files, we add the suffix 
. d to the first-level option name, yielding the filename SpaceWar. d: 


f - 

SunDefaults Version 2 


/SpaceWar 


$Help 

"A space ship battle game" 

//Friends 

"15" 

$Help 

"Number of friendly ships" 

//Enemies 

"15" 

$Help 

"Number of enemy ships" 

//Gravity 

"Yes" 

$Help 

"Affects whether star attract ships" 

$Enumeration 

ti tt 

Yes 

n •• 

Yes/$Help 

"Stars attract ships" 

No 

•t H 

No/$Help 

"Ships are immune to attraction" 

//Name 

"Battlestar" 

$Help 

"Name of your space ship" 

//Direction 

"North" 

$Help 

"Starting window border" 

$Enumeration 

•• H 

North 

ii ii 

North/$Help 

"Ships start at north window border" 

South 

ii •• 

South/$Help 

"Ships start at south window border" 

East 

•i H 

East/$Help 

"Ships start at east window border" 

West 

H H 

West/$Help 

"Ships start at west window border" 

Note that the highest-level option name, / SpaceWar, has no associated value, 
since it wouldn’t make sense to have one. If a database routine tries to access an 


option which has no value, the special string DEFAULTS_UNDEFINED will be 
returned. 
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10.4. Retrieving Option 
Values 


Retrieving String Values 


Retrieving Integer Values 


A simple programmatic interface is provided to retrieve option values from the 
defaults database. All values are stored as strings, and may be retrieved with 
def ault s_get_str ing (). For convenience, similar get routines are pro¬ 
vided to retrieve values as integers, characters, or enumerated types. The get rou¬ 
tines are described below. 

To retrieve a string value, use: 
char * 

defaults_get_string(option_name, default_value, 0) 
char *option_name; 
char *default_value; 

option_name is the name of the option whose value will be retrieved, 
default is a value to return if the option is not found in the database or if the 
database itself cannot be accessed for any reason. Note that this value should 
match the default value in the master database. The final argument to all 
default s_get* () routines is zero. 27 In our Space Wars example in the pre¬ 
vious section, we would call 

-s 

ship = defaults_get_string("/SpaceWar/Name", 

"Battlestar”, 0); 

V_ ) 

On return, ship would point to the string Battlestar. 

Suppose you misspelled the option name Name as Nane. Since 
/SpaceWar/Nane is not in the defaults database, the fail-back value of 
Battlestar will be returned and an error message may be output. 28 

To retrieve an integer value, use: 
int 

defaults_get_integer(option_name, default_value, 0) 
char *option_name; 
int default_value; 

This function gets the option value associated with option_name, treats it as a 
decimal integer, and returns the integer value. For example, the string " 17 " 
parses into the number 17 and the string " -12 3 " parses into the number -123. 
If option_name can’t be found, or its associated value can’t be parsed, the 
integer passed in for def ault_value is returned. For example, the call 


defaults_get_integer("/SpaceWar/Enemys", 15, 0); 


will return the integer 15, since "Enemies" was misspelled as "Enemys". 


27 This third argument is not currently used. It is necessary for compatibility with future releases of the 
defaults database package, which may use the third argument to return status information. 

28 Whether or not the database retrieval routines generate error messages on error conditions depends on the 
setting of the option Error Action. See Section 10.7, Error Handling , below. 
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Retrieving Character Values 


Retrieving Boolean Values 


The function def aults_get_integer_check () is the same as 

def aults_get_integer (), except that it checks that the returned value is 

within a specified range: 


int 


defaults_get_integer_check(option_name, default_value. 


min, max, 0) 


char *option_name; 
int default_value; 
int min, max; 

If the option value is not between min and max, the integer passed in for 
def ault_value is returned and an error message may be output. 

To retrieve a character value, use: 


defaults_get_character(option_name, default_value, 0) 
char *option_name; 
char default_value; 

def ault s_get_character () returns the first character from the option 
value. If the option value contains more than one character, the character passed 
in for def ault_value is returned and an error message is output. 

To retrieve a boolean value, 29 use: 


Bool 


defaults_get_boolean(option_name, default_value, 0) 
char *option_name; 

Bool default_value; 

def ault s_get_boolean () returns True if the option value is True, Yes, 
Enabled, Set, Activated, or 1 and False if the option value is False, 
No, Off, Disabled, Reset, Cleared, Deactivated, or 0. If the option 
value is not one of the above, the value passed in for def ault_value is 
returned and an error message is output. 


29 The definition forBool, found in <sunwindow/sun.h>, is: typedef enum {False = 0, 
True - 1} Bool;. 


Retrieving Character Values 


Retrieving Boolean Values 
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Retrieving Enumerated Values 


Searching for Specific Symbols 


You can retrieve enumerated option values with default s_get_string (), 
then use strcmp(3) to test which value was returned. As an alternative, you 
may find it more convenient to define an enumerated type corresponding to the 
option values, and use defaults_get_enum () to return the option value as 
the corresponding enum. The definition is: 

int 

defaults_get_enum(option_name , pairs) 
char *option_name; 

Defaults_pairs pairs[]; 

pairs is a pointer to an array of Def aults_pairs which contains name- 
value pairs. Def aults_pairs is defined as: 

typedef struct { 

char *name; 
int value; 

} Defaults_pairs; 

The array passed in as pairs must be null-terminated. 

def ault s_get_enum () returns the name associated with the value which 
is the current value of the option. If no match is found, the value associated 
with the last (null) entry is returned. 


The following example, using the direction option for our Space Wars example, 
illustrates the usage of default s_get_enum (): 


f " .J .1 . 

\ 

typedef enum {North, South, East, 
directions dir; 

West} directions; 

Defaults_j?airs direction_pairs [] 
’’North”, (int) North, 
"South", (int) South, 
"East", (int) East, 

"West", (int) West, 

- { 

NULL, (int) North}; 

/* Error value */ 

dir = defaults_get_enum("/SpaceWar/Direction", direction_pairs); 

v_ 

_ > 


To probe the defaults database to see whether or not a particular symbol is stored 
in it, use the def ault s_exists () routine. This routine will return TRUE, if 
path_name has a value defined in the defaults database. Otherwise a value of 
FALSE will be returned. 

- \ 

Bool flagl = defaults_exists("/SpaceWar/Ship_name", NULL); 

Bool flag2 = defaults_exists("/SpaceWar/Fred", NULL); 

S___ 

flagl has a value of TRUE; f lag2 has a value of FALSE. 
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Searching for Specific Values To find the original value of a particular database entry before the client’s per¬ 
sonalized database overwrites it, use 

r ---\ 

defaults_get_default(path_name, default_value, status) 

v___ , 


For example, assume that the master database has the entry 

/SpaceWar/ShipName "Lollipop" 

and that the client’s private database is 

/SpaceWar/ShipName "Death Avenger" 

If you call def aults_get_string ("/SpaceWar/ShipName", 
"<err>", NULL)" it will return Lollipop. If, however, 
the path_name is not in the database, then the default 
value will be returned. 

Retrieving all Values in the To search the database to find all of the values in the database, use the routines 

Database defaults_get_child () and def aults_get_sibling (). The routine 

def ault s_get_child (path_name, status) returns the simple name 

of the the database entry immediately under path_name. If you use 

def aults_get_child ("/SpaceWar", NULL) it will return Ship- 

Name. You can use spr intf (3S) to construct the full path name: 

—- 

char temp[1000], *child; 

child = defaults_get_child("/SpaceWar", NULL); 
if (child == NULL) { 

(void)fprintf(stderr, "Error"); 
exit(1); 

) 

sprintf(temp, "%s/%s", "/SpaceWar", child); 

V-—__, 


temp would contain / SpaceWar/ShipName. A NULL value is returned in 
there is no child. 


def ault s_get_sibling (path_name, status) returns the simple 
name of the next database entry immediately following pathname at the same 
level. So, if you use 

defaults_get_sibling ("/SpaceWar/ShipName", NULL) it will 
return Framus. This can be assembled into a full path name using 
sprintf(3S). 


char temp[1000], *sibling; 

sibling = defaults_get_sibling("/SpaceWar/ShipName"); 
if (sibling == NULL) { 

(void)fprintf(stderr, "Error"); 
exit(1); 

} 

sprintf(temp, "%s/%s", "/SpaceWar", sibling); 


'v microsystems 


Revision A, of May 9,1988 








154 Sun View 1 System Programmer’s Guide 


The following program will dump the entire contents of the defaults database 
along with their associated values. 

— 

void 

dump_defaults(path_name, indent) 
char *path_name; 

char *indent; 

{ 

char temp[1000]; 
char *child; 

(void)printf("%s%s %s0, indent, path_name, 

(defaults_get_string(path_name, "<err>", NULL )); 
child = defaults_get_child(path_name, NULL); 
if (child == NULL) { 
return; 

} 

len - strlen(indent); 
indent[len] = ''; 
indent[len+1] = ' '; 

(void) sprint f (temp, "%s/%s", path_name, child); 
dump_defaults (temp, indent) ; 

while (sibling = defaults_get_sibling(temp, NULL) 

!= NULL) { 

(void) sprintf (temp, "%s/%s", path_name, 

sibling); 

(dump_defaults(temp, indent); 

} 

} 

main () 

{ 

char indent_buf [100] = 
dump__defaults ("/", indent); 

} 

v_ * 


10.5. Conversion Programs The defaults package provides a mechanism to convert from an existing customi¬ 
zation file, such as .mailrc, to the .d format used by def aultsedit. 

You must write a separate program to do the conversion each way. Specify the 
name of the program converting from the existing customization file to the 
defaults format as the value of the $Specialf ormat_to_def ault s option 
in the corresponding . d file. The program to go the other way is specified as 
$Defaults_to_specialformat. 


As an example, at Sun we have written programs to convert from the traditional 
.mailrc file to the defaults format. The file 
/usr/lib/defaults/Mail. d contains the lines: 


/Mail 

//$Specialformat_to_defaults "mailrc_to_defaults" 
//$Defaults_to_specialformat "defaults_to_mailrc" 
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If a program is specified as the value for $Specialf ormat_to_def aults, 
then def aultsedit runs the program the first time it needs to display the 
options for that category. When the user saves the changes she or he has made to 
the database, and any changes that were made to the category, then the 
$Defaults_to_specialf ormat program is run. 

To write your own conversion programs, use the following guidelines. Read the 
customization file into the program. Then, to go from the customization file to 
.defaults, you simply figure out the appropriate option value to set, and set it 
with the routine def ault s_set_string () . 30 To go the other way, retrieve 
the value from the defaults database with the appropriate get routine, then make 
the appropriate change to the customization file. 

Note: Conversion programs should use the master database, regardless of the 
setting of the def aultsedit option Private-only. To do this, call the function 
def ault s_special_mode () as the first statement of your program. 

10.6. Property Sheets Many window programs have property sheets that the end-user can use to modify 

the behavior of their programs. You may use the defaults database to store the 
information set by the user. 

The following discussion uses code fragments taken from the default Jiler pro¬ 
gram printed at the end of this chapter. 

The filer program has a property sheet that consists of one item, the flags to pass 
through to the 1 s command. This property is represented as a string. When the 
property sheet is popped up it is necessary to read the value from the database: 
r --\ 

char *filer_flags; 

filer_flags = defaults_get_string("/Filer/LsFlags", "-l”, 

NULL); 

v-—___, 


When, the user changes the flags property, it is necessary to store the new value 
into the database. This is done using 

defaults_set_string(path_name, new_value, status). 

For example: 

f > 
filer_flags = code from example; 

defaults_set__string(”/Filer/LsFlags", filer_flags, NULL); 

V_ 


30 defaults_set_string () is documented in <de fault s/defaults .h>. 
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10.7. Error Handling 


Error Action 


This code writes the new value into the defaults database in memory. The new 
value will not be stored in the file system until the user pushes the Done button. 
When this occurs, the routine defaults_write_changed (f ile_name, 
status ) is called. This routine will write any database values in memory that 
are different from the ones in the master database to the defaults file 
f ile_name. If f ile_name has a value of NULL, then it will be written out to 
the user’s private defaults database file. So, 

-—— v 

defaults_write_changed(NULL, NULL); 

L_ J 

will cause the defaults values to be stored to ~ /. default s. 

If the user pushes the Reset button, then you want to reset the property sheet to 
be the value that the property sheet had when it first came up. A call to 
defaults_reread (path_name, status) will restore the database 
under path_name from the file system. So, 

-\ 

defaults_reread("/Filer", NULL); 

V_ ) 

will restore the defaults database for the filer property sheet. You can obtain the 
original value by reentering the property sheet display code to obtain the original 
values. 

The defaults routines report errors by printing messages on the standard error 
stream stderr. The most common cause for getting error messages is that a 
program that uses the defaults database is copied from somewhere without also 
copying the associated master defaults database file. While these messages are 
annoying, in general the program will continue to work, since every routine that 
accesses the defaults database has a def ault_value argument that will be 
returned if an option is not present in the database. 31 

Using def ault sedit, the user can set two options for the defaults database 
itself to control error reporting: 

Error_Action controls what happens when an error is encountered. Possible 
values are: 

□ Continue: print an error message and continue execution. 

□ Suppress: no action is taken. 

□ Abort: print an error message and terminate execution on encountering the 
first error. 

Most users will want to set Error Action to either Continue or Suppress. Use 
Suppress if you are getting all sorts of extraneous defaults error messages. Abort 
is useful for forcing programmers to track down extraneous error messages prior 
to releasing software to a larger community. 

31 These error messages are not printed when Private_only is True. 
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MaximumErrors Maximum_Errors puts a limit on the number of error messages which will be 

printed regardless of the setting of Error Action. 

TestJAode The option TestJAode is provided to facilitate the testing of software prior to 

release to a larger community. Use it to check for incorrect values for the 
def ault_value argument to the get routines. When Test_Mode is set to 
Enable, the defaults database is made inaccessible. In this mode, every time an 
option value is accessed, a diagnostic message is generated and the value passed 
in as def ault_value is returned. 

Note that once enabled, TestJAode can not be disabled using def ault sedit. 
This is one time when you must edit your . defaults file by hand, to set the 
TestJAode option to Disabled (or remove the entry altogether). 

10.8. Interface Summary The following table lists and explains all of the procedures that may be used to 

make use of the defaults database. 


Table 10-2 Default Procedures 


Routine 

Description 

Bool 

defaults_exists(path_name, status) 
char *path_name; 
int *status; 

Returns TRUE if path_name exists in the 
database. 

Bool 

defaults_get_boolean (option_name, default, 0) 
char *option_name; 

Bool default; 

Looks up path_name in the database and returns 

TRUE if the value is True, Yes, 

On, Enabled, Set, Activated, or 1. 

FALSE is returned if the value is False, No, Off, 
Disabled, Reset, Cleared, Deactivated, 
or 0. If the value is not one of the above values, 
then a warning message is displayed and the default is 
returned. 

char 

def ault s_get__character (opt ion_name, default, 0) 
char *option_name; 
char default; 

Looks up path_name in the defaults 
database and returns the resulting character value. 

The default value is returned in an error occurs. 

char * 

default s_get_child (path_name, status) 
char *path_name; 
int *status; 

Returns a pointer to the simple name associated with 
the next sibling of path_name. NULL will be returned 
if path_name does not exist or if path__name does 
not have an next sibling 
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Table 10-2 Default Procedures—Continued 


Routine 


Description 

char * 

defaults_get_default(path_name, default, 

status) 

Returns the value associated with path_name 

char *path_name; 


prior to being overridden by the clients private database. 

char *default_value; 


default is returned in any error occurs. 

int *status; 

int 


Looks up the values associated with path_name, scans 

defaults get enum(option name, pairs, 0) 


the pairs table, and returns the associated value. If no 

char *option name; 


match can be found, then an error will be generated and 



the value associated with the last entry will be returned. 

Defaults^pairs *pairs; 


(See default s_lookup ().) 

int 

defaults_get_integer (option_name, default, 0) 

Looks up path_name in the defaults database 

char *option_name; 


and returns the resulting integer. The default value is 

int default; 


returned if any error occurs. 

int 

default s__ge t__i nt ege r_che ck (opt ion_name, 

default_value. 

Looks up path_name in the defaults database 

min, max, 0) 


and returns the resulting value. If the value 

char *option_name; 


in the database is not between minimum and 

int default_value; 


maximum (inclusive), then an error message will be 

int min, max; 


printed. The default will be returned if an error 

occurs. 

char * 

defaults_get_sibling(path_name, status) 


Returns a pointer to the simple name associated with the 

char *path_name; 


next sibling of path__name. NULL will be returned, if 

int *status; 


path_namedoes not exist or if path name does not 

- 


have an next sibling. 

char * 


Looks up path_name in the defaults database 

defaults_get_string(option_name, default 

, 0) 

and returns the string value associated with it 

char *option_name; 


The default will be retuned if any error occurs. 

char *default; 

void 


Rereads the portion of the database associated with 

default s_reread (path__name, status) 


path_jname. 

char *path_name; 

int * status; 

defaults_set_character(path_name, value. 

status) 

Sets path_name to value, while value 

char *path__name; 


is a character. 

char value; 

int *status; 
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Table 10-2 Default Procedures—Continued 



Routine 


Description 

void 




defaults_ 

set_enumeration(path_name, value, status) 

Sets path_name to value, where value 

char 

*path_name; 


is a pointer to a string. 

char 

*value; 



int 

*status; 



void 




defaults 

set__integer (path_name, value. 

status) 

Sets path_name to value, where value 

char 

*path_name; 


is an integer. 

int 

value; 



int 

*status; 



void 




defaults 

set string(path_name, value. 

status) 

Sets path_name to valuewhere value 

char 

*path_name; 


is a pointer to a string 

char 

*value; 



int 

*status; 



void 



Causes the database to behave as if the entire master 

default s_ 

_special_mode() 


database has been read into memory prior to reading in 
the private database. This is done to insure that the order 
of nodes that default sedit presents is the same as 
that in the . d files, regardless of what the user happens 
to have set in his or her private database. 

void 




default s_ 

write__all (pathjname, file_name, status) 

Writes out all of the data base nodes from 

char 

*path_name; 


path_name and below into f ile_name. Out_f ile 

char 

*file_name; 


is the string name of the file to create. If f ile_name is 

int 

*status; 


NULL, then env var DEFAULTS_FILE will be used. 

void 



Writes out all of the private database entries to 

default s_ 

char 

int 

_write__changed (file_name, status) 

*file_name; 

*status; 

f ile_name. Any time a database node is set, it 
becomes part of the private database. If the value of the 
Filename is NULL, then DEFAULTS_FILE will be 
used. 

void 




defaults_ 

_write_differences(file_name. 

status) 

Writes our all of the database entries that differ 

char *file_name; 


from the master database. Out_File is the string 

int 

*status; 


name of the file to create. If f ile_name is NULL, 




env var DEFAULTS_FI LE is used. 
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10.9. Example Program: 
filer Defaults Version 


The following program is a variation of the filer program discussed in the Sun- 
View 1 Programmer’s Guide. It uses some of the defaults procedures discussed 
in this chapter. 


/*****************************************************************************/ 
/* 4.0 f iler_default. c */ 

/*****************************************************************************/ 


#include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 

♦include 


< suntool/sunview.h> 

<sunwindow/defaults.h> 

<suntool/panel.h> 

<suntool/tty.h> 

<suntool/textsw.h> 

<suntool/seln.h> 

<suntool/alert.h> 

<sys/stat.h> /* stat call needed to verify existence of files 


*/ 


/* these objects are global so their attributes can be modified or retrieved */ 


Frame 
Panel 
Tty 

Textsw 
Panel_item 
int 

char *compose_ls_options () ; 


base_frame, edit_frame, ls_f lags_f rame; 

panel, ls_flags_panel; 

ttysw; 

editsw; 

dir_item, fname_item, filing_mode_item, reset_item, done_item; 
qu i t__conf i rmed_f rom_pane 1 ; 


♦define MAX_F I LENAME_LEN 256 

♦define MAX PATH LEN 1024 


char *getwd(); 

main(argc, argv) 
int argc; 
char **argv; 

{ 

static Notify_value filer_destroy_func(); 
void ls_flags_proc () ; 

base_frame = window_create (NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "filer", 

FRAME_PROP S_ACT I ON_PROC, 1 s_f 1 ag s_pr oc, 

FRAME_PROPS_ACTIVE, TRUE, 

FRAME_NO_CONFIRM, TRUE, 

0 ); 

(void) notify_interpose_destroy_func (base_frame, filer_destroy_func) ; 

create_panel__subwindow () ; 
create__tty_subwindow () ; 
create_edit_popup () ; 
create_ls_f lags_popup (); 
quit__confirmed_f rom__panel = 0; 


window_main_loop (base_frame) ; 
exit(0); 
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create_tty_subwindow () 

{ 

ttysw = window__c reate (base_frame, TTY, 0); 

} 

create_edit_popup() 

{ 

edit__frame = window__create (base_frame, FRAME, 
FRAME_SHOW_LABEL, TRUE, 

0 ); 

editsw = window_create (edit__f rame, TEXTSW, 0) ; 

} 


create_panel_subwindow() 

{ 

void ls_proc () , ls_f lags_j)roc () , quit_proc () , edit_proc () , 
edit__sel_j?roc () , del_proc () ; 

char current_dir [MAX_PATH_LEN] ; 

panel = window_create (base_frame, PANEL, 0) ; 


(void) panel_create_item(panel, 
PANE L__LABE L_X, 

PANE L_LABE L_Y, 

PANEL_LABE L_IMAGE, 
PANEL_NOTIFY_PROC, 

0 ); 


PANEL_BUTTON, 

ATTR_COL(0), 

ATTR_ROW(0), 

panel__button_image (panel, "List Directory", 
ls_proc. 


0 , 0 ), 


(void) panel_create_item(panel, 
PANE L_LABE L_IMAGE, 

P ANEL_NOT I FY__PR0C, 

0 ); 


PANEL_BUTTON, 

panel_button_image(panel, "Set Is flags", 
ls_flags_proc. 


0 , 0 ), 


(void) panel__create__item(panel, 
PANEL_LABEL_IMAGE, 

PANEL_NOTIFY_PROC, 

0 ); 


PANEL_BUTTON, 

panel_button_image (panel, "Edit", 
edit_j?roc. 


0 , 0 ), 


(void) panel_create_item(panel, 
PANEL_LABE L_IMAGE, 

PANEL_NOTIFY_PROC, 

0 ); 


PANEL_BUTTON, 

panel_button_image(panel, 
del_j?roc. 


"Delete", 0, 0), 


(void) panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Quit", 0, 0), 

PANEL_NOTIFY_PROC, quit_proc, 

0 ) ; 


f iling_mode__item = panel_c reate 
PANE L_LABE L_X, 
PANEL_LABEL_Y, 

P ANEL_LABEL__STR ING, 
PANEL_CHOICE_STRINGS, 

0 ); 


item(panel, PANEL_CYCLE, 
ATTR__C0L (0) , 

ATTR_ROW(l), 

"Filing Mode:", 

"Use \"File:\" item", 

"Use Current Selection", 0, 


(void) panel_create_item(panel, PANEL_MESSAGE, 
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PANEL LABEL X, 

ATTR_C0L(0), 

> 



PANEL_LABEL_Y, 

ATTR_R0W(2), 




o 





dir item * panel__create_item(panel. 

PANEL_TEXT, 




PANEL LABEL X, 

ATTR_C0L(0), 




PANEL LABEL_Y, 

ATTR_R0W(3), 




PANEL VALUE DISPLAY LENGTH, 

60, 




PANEL_VALUE, 

getwd(current_dir), 




PANEL LABEL_STRING, 

"Directory: ", 




0); 





fname item = panel_create_item (panel, PANEL_TEXT, 




PANEL LABEL X, 

ATTR_C0L(0), 




PANEL LABEL Y, 

ATTR_R0W(4), 




PANEL LABEL DISPLAY_LENGTH, 

60, 




PANEL_LABE L_STRING, 

"File: ", 




o 





window_fit_height(panel); 




} 

window_set(panel, PANEL_CARET_ITEM, 

fname__item, 0); 



typedef struct Filer { 




}; 

char *flags; 

char *path; 




struct Filer f iler__options = {" ", 

r "/Filer/Options"}; 




struct Filer filer_format * {" 1 ", 

"/Filer/Format"}; 




struct Filer filer_sort_order = {" ] 

c ", "/Filer/Sort_0rder"}; 




struct Filer filer__sort_criterion = 

{" tu", "/Filer/Sort_Criterion"}; 




struct Filer filer_directories = {" 

d ", "/Filer/Sort_Directories"}; 




struct Filer filer_recursive = {" R 

", "/Filer/Recursive"}; 




struct Filer filer_file_type = {" F 

", "/Filer/File_Type"}; 




struct Filer filer_dot_files = {" a 

", "/Filer/Dot_Files"}; 



create_ls flags_popup() 

{ 





void done__proc () ; 
void reset__proc (); 





ls_flags_frame * window_create (base 

_frame, FRAME, 0); 




ls_flags_panel = window_create (ls_flags__f rame, PANEL, 0); 




pane l_c re at e__i t e m (1 s_f lags_jpanel, PANE L_ME S S AGE, 




PANEL_ITEM_X, 

ATTR_C0L(14), 




PANEL_ITEM_Y, 

ATTR_ROW(0), 




PANE L_LABEL_ST RING, 

"Options for Is command". 




PANE L_CL I ENT__D ATA, 

&fi1er_options, 




0); 





panel_create_item(ls_flags_panel, PANEL_CYCLE, 




P ANEL__I TEM_X, 

ATTR__C0L (0) , 




P ANEL__I TEM_Y, 

ATTR_R0W(1), 


\ _ 


PANEL_D I SPLAY_LEVEL, 

PANEL_CURRENT, 
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r 

PANE L_LABE L_S T RIN G, 

"Format: 

A 


PANEL_CHOICE_STRINGS, 

"Short", "Long", 0, 



PANEL CLIENT DATA, 

&filer format. 



o 




panel_create_item(ls_flags_panel. 

PANE L_CY CLE, 



PANEL_ITEM_X, 

ATTR_C0L(0), 



P ANEL__I TEM_Y, 

ATTR_R0W (2) , 



PANEL_DISPLAY_LEVEL, 

PANEL_CURRENT, 



PANEL_LABEL_STRING, 

"Sort Order: ", 



PANEL__CH01 CE_STRI NGS, 

"Descending", "Ascending", 0, 



PANEL CLIENT DATA, 

0); 

&filer sort order. 



panel_create_item(ls_flags_panel. 

PANE L_CY CLE, 



P ANEL__I TEM_X, 

ATTR__C0L (0) , 



PANEL_ITEM_Y, 

ATTR_R0W(3), 



PANEL_DISPLAY_LEVEL, 

PANEL CURRENT, 



PANEL__LABEL_STRING, 

"Sort criterion: ", 



PANEL_CHOICE_STRINGS, 

"Name", "Modification Time", 

"Access Time", 0, 



PANEL CLIENT DATA, 

&filer sort criterion. 



o 




panel_create_item(ls_flags_panel. 

PANEL_CYCLE, 



PANEL_ITEM_X, 

ATTR_C0L(0), 



PANEL_ITEM_Y, 

ATTR_R0W(4), 



PANEL_D IS P LA Y_LE VE L, 

PANEL_CURRENT, 



PANEL_LABEL_STRING, 

"For directories, list: ", 



PANEL_CHOICE_STRINGS, 

"Contents", "Name Only", 0, 



PANE L_CL I ENT__D ATA, 

&filer_directories, 



o 




p an e l_c r e a t e__i t e m (1 s_f 1 a g s__pa n e 1, 

PANEL_CYCLE, 



PANEL_ITEM_X, 

ATTR_C0L(0) , 



P ANEL_I TEM__Y, 

ATTR_R0W(5), 



PANELJDISPLAY_LEVEL, 

PANEL_CURRENT, 



PANEL_LABEL_STRING, 

"Recursively list subdirectories? ", 



PANEL_CHOICE_STRINGS, 

"No", "Yes", 0, 



PANEL CLIENT DATA, 

0); 

&filer_recursive. 



panel_create_item(ls__flags_jpanel. 

PANE L__C Y CLE, 



PANEL_ITEM_X, 

ATTR_COL(0), 



P ANEL_I TEM__Y, 

ATTR_R0W(6), 



PANEL_DISPLAY_LEVEL, 

PANEL_CURRENT, 



PANEL_LABEL_STRING, 

"List files? 



PANE L_CH01CE_STRINGS, 

"No", "Yes", 0, 



PANEL CLIENT DATA, 

0); 

& f i 1 e r__do t_f i 1 e s, 



panel_create_item(ls_flags_panel. 

PANE L_C Y CLE, 



PANEL_ITEM_X, 

ATTR_C0L(0), 



PANEL__ITEM_Y, 

ATTRJR0W(6), 



P ANEL_D I SPLAY_LEVEL, 

PANEL_CURRENT, 



PANEL__LABEL_STRING, 

"Indicate type of file? ", 



PANEL_CHOICE_STRINGS, 

"No", "Yes", 0, 



PANEL_CLI ENT_DATA, 

&filer_file_type. 
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0 ); 


done_item =* panel_create_item (ls_f lags_panel, PANEL__BUTTON, 
PANEL__I TEM_X, ATTR_COL (1) , 

P ANEL_I TEM_Y , ATTR_ROW (8) , 

PANEL_LABEL__IMAGE, panel_button_image (panel, 

PANE L_N OTIF Y_P ROC, done_j?roc, 

0 ); 


"Done", 6, 0) , 


reset_item = panel_create_item (ls_f lags_panel, PANEL_BUTTON, 

PANEL__I TEM_X, ATTR__COL (12), 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Reset", 6, 0), 

PANE L_N OTIFY_PROC, re set_proc, 

0 ); 


} 


(void)compose_ls_options (1); 
window_fit(ls_f lags_j?anel); /* 
window_fit(ls_flags_frame); /* 


fit panel around its items */ 
fit frame around its panel */ 


char * 

compose_ls_options (control) 
int control; 


{ 


static char 

char 

char 

int 

Panel_item 
struct Filer 
int 


flags[20]; 
*ptr; 
flag; 

first_flag = 
item; 

*client_data; 

index; 


TRUE; 


ptr = flags; 

panel_each_item (ls__flags_panel, item) 

if ((item != done_item) && (item != reset_item)) { 
client_data = (struct Filer *)panel_get(item, 

PANEL__CLIENT_DATA, 0) ; 

switch (control) { 
case 0: 

index = (int) panel_get__value (item) ; 

defaults_set_integer((char *)client_data->path, 

(int)index, (int *)NULL); 

break; 
case Is 

index = defaults_get__integer((char *)client_data->path, 
(int)1, NULL); 

panel_set__value (item, index) ; 
break; 

case 2: 

flag = client_data->flags[index]; 
if (flag !=''){ 

if (first_flag) { 

*ptr++ = ' ; 

first_flag = FALSE; 

} 

*ptr++ = flag; 

} 

} 
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} 

panel_end_each 
*ptr - 'Non¬ 
return flags; 

} 

void 

ls_j?roc () 

{ " 

static char previous_dir [MAX_PATH_LEN] ; 
char *current_dir; 

char cmdstring[100]; /* dir_item's value can be 80, plus flags */ 

current_dir = (char *)panel_get_value(dir_itern); 

if (strcmp(current_dir, previous_dir)) { 

chdir((char *)panel_get_value(dir_item)); 
strcpy (previous__dir, current_dir) ; 

} 

sprintf(cmdstring, "Is %s %s/%s\n", 
compose_ls_options(), 
current_dir, 

panel_get_value(fname_item)); 
ttysw__input (ttysw, cmdstring, strlen (cmdstring) ) ; 

} 

void 

ls__f lags_j?roc () 

{ " 

window_set (ls_flags_f rame, WIN__SHOW, TRUE, 0) ; 

} 

void 

done_proc () 

{ 

window_set (ls_flags__frame, WIN_SHOW, FALSE, 0) ; 

(void) compose_ls__options (0); 
defaults_writexchanged(NULL, NULL); 

} 

void 

reset_proc () 

{ 

defaults__reread ("/Filer" , NULL) ; 

} 

/* return a pointer to the current selection */ 
char * 

get_selection () 

{ 

static char filename[MAX_FILENAME_LEN]; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire (SE LN__PR I MARY) ; 

buffer = seln_ask(^holder, SELN_REQ_CONTENTS_ASCII, 0, 0); 
strncpy( 

filename, buffer->data + sizeof(Seln_attribute), MAX_FILENAME_LEN); 
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return (filename) ; 

} 

/* return 1 if file exists, else print error message and return 0 */ 
stat__file (filename) 
char *filename; 

{ 

static char previous_dir[MAX_PATH_LEN]; 
char *current_dir; 
char this_f ile [MAX_PATH_LEN] ; 

struct stat statbuf; 

current_dir = (char *)panel_get_value(dir_item); 

if (strcmp(current_dir, previous_dir)) { 

chdir((char *)panel_get_value(dir_item)); 
strcpy(previous_dir, current_dir); 

} 

sprintf (this_f ile, "%s/%s", current_dir, filename); 
if (stat(this_file, Sstatbuf) < 0) { 

char buf[MAX_FILENAME_LEN+11]; /* big enough for message */ 

sprintf(buf, "%s not found.", this_file); 
msg(buf, 1); 
return 0; 

} 

return 1; 

} 

void 

edit^proc () 

{ 

void edit_f ile_jproc () , edit_sel_proc () ; 

int file_mode = (int) panel_get_value (f iling__mode_item) ; 

if (file_mode) { 

(void)edit_sel_proc(); 

} else { 

(void)edit_file_proc (); 

} 

} 

void 

edit_file__proc () 

{ 

char *filename; 

/* return if no selection */ 

if (!strlen(filename = (char *)panel_get_value(fname_item))) { 

msg("Please enter a value for \"File:\".", 1); 
return; 

} 

/* return if file not found */ 
if (!stat_file(filename)) 
return; 

window_set(editsw, TEXTSW_FILE, filename, 0); 
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window_set(edit_jframe, FRAME_LABEL, filename, WIN_SHOW, TRUE, 0); 

} 

void 

edit_sel_j?roc () 

{ 

char *filename; 

/* return if no selection */ 
if (! strlen (filename * get__selection () ) ) { 

msg("Please select a file to edit.", 0); 
return; 

} 

/* return if file not found */ 
if (!stat_file(filename)) 
return; 

window_set (editsw, TEXTSW__FILE, filename, 0); 

window_set(edit_frame, FRAME_LABEL, filename, WIN_SH0W, TRUE, 0); 

} 

void 

del_jproc () 

{ 

char buf[300]; 

char *filename; 
int result; 

Event event; /* unused */ 

int file_mode = (int) panel_get_value (f iling_mode_item) ; 

/* return if no selection */ 
if (file_mode) { 

if (!strlen(filename = get_selection())) { 

msg("Please select a file to delete.", 1); 
return; 

} 

} else { 

if (! strlen (filename = (char *) panel_get_value (fname__item) ) ) { 

msg("Please enter a file name to delete.", 1); 
return; 

} 

} 

/* return if file not found */ 
if (!stat_file(filename)) 
return; 

/* user must confirm the delete */ 
result = alert_j5rompt(base_frame, &event, 

ALERT_MESSAGE_STRINGS, 

"Ok to delete file:", 
filename, 

0, 

ALERT_BUTTON_YES, "Confirm, delete file", 

ALERT_BUTT0N_N0, "Cancel", 

0); 
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switch (result) { 
case ALERT_YES: 

unlink(filename) ; 

sprintf(buf, "%s deleted.", filename); 

msg(buf, 0); 

break; 

case ALERT_NO: 
break; 

case ALERT__FAILED: /* not likely to happen unless out of FDs */ 
printf("Alert failed, will not delete %s.\n", filename); 
break; 

■' ) 

} 

int 

confirm_quit() 

{ 

int result; 

Event event; /* unused */ 

char *msg = "Are you sure you want to Quit?"; 

result = alert_prompt(base_frame, &event, 

ALERT_MESSAGE_STRINGS, 

"Are you sure you want to Quit?", 

0, 

ALERT JBUTTON_YES, "Confirm" , 

ALERT_BUTT 0N_N 0, "Cancel", 

0 ); 

switch (result) { 
case ALERT_YES: 
break; 

case ALERT_N0: 
return 0; 

case ALERT_FAILED: /* not likely to happen unless out of FDs */ 
printf("Alert failed, quitting anyway.\n"); 
break; 

} 

return 1; 

} 

static Notify_value 

filer_destroy__func (client, status) 

Notify__client client; 

Destroy_status status; 

{ 

if (status == DE S TROY_CHECKING) { 

if (quit_confirmed_f rom_j>anel) { 

return (notify_next_destroy__func (client, status) ) ; 

} else if (confirm_quit () === 0) { 

(void) notify__veto_destroy ( (Notify_client) (LINT__CAST (client) ) ) ; 
return(N0TIFY_D0NE); 

} 

} 

return(notify_next_destroy_func(client, status)); 

} 

void 

quit_proc () 
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{ 

if (confirm_quit()) { 

quit__confirmed_f rom_panel = 1; 
window_destroy (base_frame) ; 

} 

} 

msg(msg, beep) 
char *msg; 
int beep; 

{ 

char buf[300]; 

int result; 

Event event; /* unused */ 

char *contine_msg = "Press \"Continue\" to proceed."; 

result = alert^prompt(base_frame, Sevent, 

ALERT_MESSAGE__STRINGS, 
msg, 

contine_msg, 

0, 

ALERT_NOJBEEPING, (beep) ? 0:1, 

ALERT_BUTTON_YES, "Continue", 

ALERT_TRIGGER, ACTI0N_ST0P, /* allow either YES or NO answer */ 

0 ); 

switch (result) { 
case ALERT_YES: 

case ALERT_TRIGGERED: /* result of ACTION_STOP trigger */ 
break; 

case ALERT_FAILED: /* not likely to happen unless out of FDs */ 
printf("Alert failed, continuing anyway.\n"); 
break; 

} 

} 
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Advanced Imaging 


11.1. 




Handling Fixup 


The chapter covers some topics on low level image maintenance. There is also a 
section on icon manipulation. 

The routines pw_read (), pw_copy () and pw_get () may find themselves 
thwarted by trying to read from a portion of the pixwin which is hidden, and 
therefore has no pixels. This can happen with a canvas that you have made non- 
retained. When this happens, pw_fixup (a struct rectlist) in the 
pixwin structure will be filled in by the system with the description of the 
source areas which could not be accessed. The client must then regenerate this 
part of the image into the destination. Retained pixwins will always return 
rl_null in pw_f ixup because the image is refreshed from the retained 
memory pixrect. 

The usual strategy when calling pw_copy () is to call the following routine to 
restrict the pixwin’s clipping to just that part of the image that needs to be fixed 
up. 

pw_restrict_clipping(pw, rl) 

Pixwin *pw; 

Rectlist *rl; 

You pass in &pw->pw_fixup as rl. Now you draw your entire pixwin. Only 
the parts that need to be repaired are drawn. Now you need to reset your pixwin 
so that you may access its entire visible surface. 

pw_exposed(pw) 

Pixwin *pw; 

pw_exposed () is the call that does this. 

Dealing with fixup for pw_read () or pw_get () is really quite ludicrous. 

One should really run these retained if they are using the screen as a storage 
medium for their bits. 
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11.2. Icons 


Loading Icons Dynamically 


Icon File Format 


The basic usage of icons is described in the Icons chapter of the SunView 
Programmer s Guide. The opaque type Icon, and the functions and attributes 
by which icons are manipulated, are defined in the header file 
<suntool/icon.h>. 

Applications such as icon editors or browsers, which need to load icon images at 
run time, will need to use the functions described in this section. The definitions 
necessary to use these functions are contained in <suntool/icon_load. h>. 

You can load an icon’s image from a file with the call: 
int 

icon_load(icon, file, error_msg) 

Icon icon; 

char *file, *error_msg; 

Icon is an icon returned by icon_create (); file is the name of a file 
created with iconedit. error_msg is the address of a buffer (at least 256 char¬ 
acters long) into which icon_load () will write a message in the event of an 
error. If icon_load () succeeds, it returns zero; otherwise it returns 1. 

The function 

int 

icon_init_from_pr(icon, pr) 

Icon icon; 

Pixrect *pr; 

initializes the width and height of the icon’s graphics area (attribute 
ICON_IMAGE_RECT) to match the width and height of pr. It also initializes 
the icon’s label (attribute ICON_LABEL) to NULL. The return value is meaning¬ 
less. 

To load an image from a file into a pixrect, use the routine: 

Pixrect * 

icon_load_mpr(file, error_msg) 
char *file, *error_msg; 

This function allocates a pixrect, and loads it with the image contained in file. 
If no problem is encountered, icon_load_mpr () returns a pointer to the new 
pixrect containing the image. If it can’t access or interpret the file, 
icon_load_mpr () writes a message into the buffer pointed to by 
error_msg and returns NULL. 

iconedit writes out an ASCII file consisting of two parts: a comment describing 
the image, and a list of hexadecimal constants defining the actual pixel values of 
the image. The contents of the file <images/template. icon> are repro¬ 
duced below, as an example: 
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/* Format_version=l, Width=16, Height=16, Depth=l, Valid_bits_per_item=16 

* This file is the template for all images in the cursor/icon library. 

* The first line contains the information needed to properly interpret 

* the actual bits, which are expected to be used directly by software 

* that wants to do compile-time binding to an image via a #include. 

* The actual bits must be specified in hex. 

* The default interpretation of the bits below is specified by the 

* behavior of mpr_static. 

* Note that Valid_bits_per_item uses the least-significant bits. 

* See also: icon_load.h. 

* Description: A cursor that spells "TEMPLATE” using two lines, with a 

* solid bar at the bottom. 

* Background: White 
*/ 

0xED2F, 0x49E9, 0x4D2F, 0x4928, 0x4D28, 0x0000, 0x0000, 0x8676, 
0x8924, 0x8F26, 0x8924, 0xE926, 0x0000, 0x0000, OxFFFF, OxFFFF 


The first line of the comment is composed of header parameters, used by the icon 
loading routines to properly interpret the actual bits of the image. The 
f ormat_ver sion exists to permit further development of the file format in a 
compatible manner, and should always be 1. Default values for the other header 
parameters are Depth=l, Width=64, Height=64, 
Valid_bits_per__item=16. 


The remainder of the comment can be used for arbitrary descriptive material. 


The following function is provided to allow you to preserve this material when 
rewriting an image file: 


FILE * 

icon__open__header (f ile, error_msg, info) 
char *file, *error_msg; 

icon header handle info; 


typedef struct icon_header_object { 
int depth, 
height, 

format_version, 

valid_bits_per_item, 

width; 

long last_j?aram_j?os; 

} icon_header_object; 

icon_open_header fills in info from file's header parameters, 
inf o->last_param_pos is filled in with the position immediately after the 
last header parameter that was read. The FILE * returned by 
icon_open_header () is left positioned at the end of the header comment. 
Thus f tell (icon_open_header () ) indicates where the actual bits of the 
image should begin, and the characters in the range 


[info->last_param_pos...ftell(icon_open_header()] 

encompass all of the extra descriptive material contained in the file’s header. 
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11.3. Damage 


Handling a SIGWINCH 
Signal 


Image Fixup 


This section is included for those who can’t use the Agent to hide all this com¬ 
plexity. Try to use the Agent, because it is very hard to get the following right. 

When a portion of a client’s window becomes visible after having been hidden, it 
is damaged. This may arise from several causes. For instance, an overlaying 
window may have been removed, or the client’s window may have been 
stretched to give it more area. The client is notified that such a region exists 
either by the events WIN_REPAINT or WIN_RES IZE, or if the client is not 
using the Notifier, by the signal SIGWINCH; this simply indicates that something 
about the window has changed in a fashion that probably requires repainting. It 
is possible that the window has shrunk, and no repainting of the image is required 
at all, but this is a degenerate case. It is then the client’s responsibility to repair 
the damage by painting the appropriate pixels into that area. The following sec¬ 
tion describes how to do that. 

There are several stages to handling a SIGWINCH. First, in almost all cases, the 
procedure that catches the signal should not immediately try to repair the damage 
indicated by the signal. Since the signal is a software interrupt, it may easily 
arrive at an inconvenient time, halfway through a window’s repaint for some nor¬ 
mal cause, for instance. Consequently, the appropriate action in the signal 
handler is usually to set a flag which will be tested elsewhere. Conveniently, a 
SIGWINCH is like any other signal; it will break a process out of a select(2) 
system call, so it is possible to awaken a client that was blocked, and with a little 
investigation, discover the cause of the SIGWINCH. 

Once a process has discovered that a SIGWINCH has occurred and arrived at a 
state where it’s safe to do something about it, it must determine exactly what has 
changed, and respond appropriately. There are two general possibilities: the 
window may have changed size, and/or a portion of it may have been uncovered. 

win_getsize () (described in Windows) can be used to inquire the current 
dimensions of a window. The previous size must have been remembered, for 
instance from when the window was created or last adjusted. These two sizes are 
compared to see if the size has changed. Upon noticing that its size has changed, 
a window containing other windows may wish to rearrange the enclosed win¬ 
dows, for example, by expanding one or more windows to fill a newly opened 
space. 

NOTE If you are using window_main_loop () to drive your program, then the 

SIGWINCH is translated into a WIN_RESIZE and/or WIN_REP AINT event for 
you. The rest of this discussion still applies. 

Whether a size change occurred or not, the actual images on the screen must be 
fixed up. It is possible to simply repaint the whole window at this point — that 
will certainly repair any damaged areas — but this is often a bad idea because it 
typically does much more work than necessary. 

Therefore, the window should retrieve the description of the damaged area, repair 
that damage, and inform the system that it has done so: The pw_damaged () 
procedure: 
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pw_damaged(pw) 

Pixwin *pw; 

is a procedure much like pw__exposed (). It fills in pwcd_clipping with a 
rect list describing the area of interest, stores the id of that rectlist in the 
pixwin’s pw_opshandle and in pwcd_damagedid as well. It also stores its 
own address in pwco_getclipping, so that a subsequent lock will check the 
correct rectlist. All the clippers are set up too. Colormap segment offset 
initialization is done, as described in Surface Preparation. 


CAUTION A call to pw_damaged () should ALWAYS be made in a sigwinch handling 


routine. Likewise, pw_donedamaged () should ALWAYS be called before 
returning from the sigwinch handling routine. While a program that runs 
on monochrome displays may appear to function correctly if this advice is 
not followed, running such a program on a color display will produce pecu¬ 
liarities in color appearance. 

Now is the time for the client to repaint its window — or at least those portions 
covered by the damaged rectlist; if the regeneration is relatively expensive, 
that is if the window is large, or its contents complicated, it may be worth res¬ 
tricting the amount of repainting before the clipping that the rectlist will 
enforce. This means stepping through the rectangles of the rectlist, deter¬ 
mining for each what data contributed to its portion of the image, and recon¬ 
structing only that portion. See the chapter on rectlists for details about rectlists. 

For retained pixwins, the following call can be used to copy the image from the 
backup pixrect to the screen: 

pw_repairretained(pw) 

Pixwin *pw; 

When the image is repaired, the client should inform the window system with a 
call to: 

pw_donedamaged(pw) 

Pixwin *pw; 

pw_donedamaged () allows the system to discard the rectlist describing 
this damage. It is possible that more damage will have accumulated by this time, 
and even that some areas will be repainted more than once, but that will be rare. 

After calling pw_donedamaged (), the pixwin describes the entire visible area 
of the window. 

A process which owns more than one window can receive a SIGWINCH for any 
of them, with no indication of which window generated it. The only solution is 
to fix up all windows. Fortunately, that should not be overly expensive, as only 
the appropriate damaged areas are returned by pw_damaged (). 
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11.4. Pixwin Offset Control The following routines control the offset of a pixwin’s coordinate space. They 

can be used for writing in a fixed coordinate space even though the pixwin moves 
about relative to the window’s origin. 

void 

pw_set_x_offset(pw, offset) 

Pixwin *pw; 
int offset; 

void 

pw_set_y_offset(pw, offset) 

Pixwin *pw; 
int offset; 


void 

pw_set_xy_offset (pw, int x__offset, y_offset) 
Pixwin *pw; 

int x_offset, y_offset; 


int 

pw__get_x_of f set (pw) 
Pixwin *pw; 


int 

pw_get_y_of f set (pw) 
Pixwin *pw; 


^§un 
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.1. Full Screen Access 


This chapter describes routines that you will probably need when writing a menu 
or prompt package of your own. Note, however, that SunView’s menu and alert 
facilities documented in the SunView 1 Programmer’s Guide are both 
comprehensive full-featured packages that handle fullscreen access for you. Also 
note that you can use window_loop () together with one of the SunView win¬ 
dow types to create other kinds of full-screen prompts, again without having to 
manage fullscreen interaction yourself. 

To provide certain kinds of feedback to the user, it may be necessary to violate 
window boundaries. Pop-up menus, prompts and window management are 
examples of the kind of operations that do this. Th t fullscreen interface provides 
a mechanism for gaining access to the entire screen in a safe way. The package 
provides a convenient interface to underlying sunwindow primitives. The fol¬ 
lowing structure is defined in <suntool/f ullscreen. h>: 

struct fullscreen { 


int 

fs_windowf di¬ 

struct 

rect f s__screenrect ; 

struct 

pixwin *fs_pixwin; 

struct 

cursor fs__cachedcursor; 

struct 

inputmask fs_cachedim; /* Pick mask */ 

int 

fs_cachedinputnext; 

struct 

inputmask fs__cachedkbdim; /* Kbd mask */ 


} ; 

f s_windowf d is the window that created the fullscreen object, 
f s_screenrect describes the entire screen’s dimensions, f s_pixwin is 
used to access the screen via the pixwin interface. The coordinate space of 
fullscreen access is the same as f s_windowfd’s. Thus, pixwin accesses are 
not necessarily done in the screen’s coordinate space. Also, f s_screenrect 
is in the window’s coordinate space. If, for example, the screen is 1024 pixels 
wide and 800 pixels high, f s_windowfd has its left edge at 300 and its top 
edge at 200, that is, both relative to the screen’s upper left-hand comer, then 
f s_screenrect is {-300, -200, 1024, 800}. 

The original cursor, f s_cachedcursor, input mask, f s_cachedim, and the 
window number of the input redirection window, f s_cachedinputnext, are 
cached and later restored when the fullscreen access object is destroyed. 
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Initializing Fullscreen Mode 

struct fullscreen * 
fullscreen init(windowfd) 
int windowfd; 

gains full screen access for windowfd and caches the window state that is likely 
to be changed during the lifetime of the fullscreen object, windowfd is set to 
do blocking I/O. A pointer to this object is returned. 

During the time that the full screen is being accessed, no other processes can 
access the screen, and all user input is directed to f s->f s_windowfd. 

Because of this, use fullscreen access infrequently and for only short periods of 
time. 

Releasing Fullscreen Mode 

fullscreen_destroy(fs) 

struct fullscreen *fs; 

fullscreen destroy () restores f s’s cached data, releases the right to 
access the full screen and destroys the fullscreen data object, 
f s->f s windowf d’s input blocking status is returned to its original state. 

Seizing All Inputs 

Fullscreen access is built out of the grab I/O mechanism described here. This 
lower level is useful if you wanted to only grab input. 

Normally, input events are directed to the window which underlies the cursor at 
the time the event occurs (or the window with the keyboard focus, if you have 
split pick/keyboard focus). Two procedures modify this state of affairs. 

Grabbing I/O 

A window may temporarily seize all inputs by calling: 

win_grabio(windowfd) 
int windowfd; 

The caller’s input mask still applies, but it receives input events from the whole 
screen; no window other than the one identified by windowfd will be offered an 
input event or allowed to write on the screen after this call. 

Releasing I/O 

win_releaseio(windowfd) 
int windowfd; 

undoes the effect of a win_grabio (), restoring the previous state. 

12.2. Surface Preparation 

In order for a client to ignore the offset of his colormap segment the image of the 
pixwin must be initialized to the value of the offset. This surface preparation is 
done automatically by pixwins under the following circumstances: 

o The routine pw damaged () does surface preparation on the area of the 
pixwin that is damaged. 

□ The routine pw_put colormap () does surface preparation over the entire 

exposed portion of a pixwin if a new colormap segment is being loaded for 
the first time. 

For monochrome displays, nothing is done during surface preparation. For color 
displays, when the surface is prepared, the low order bits (colormap segment size 
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Multiple Plane Groups 


Pixel Caching 


Saving Screen Pixels 


minus 1) are not modified. This means that surface preparation does not clear the 
image. Initialization of the image (often clearing) is still the responsibility of 
client code. 

There is a case in which surface preparation must be done explicitly by client 
code. When window boundaries are knowingly violated, as in the case of pop-up 
menus, the following procedure must be called to prepare each rectangle on the 
screen that is to be written upon: 

pw_preparesurface(pw, rect) 

Pixwin *pw; 

Rect *rect; 

rect is relative to pw’s coordinate system. Most commonly, a saved copy of 
the area to be written is made so that it can be restored later — see the next sec¬ 
tion. 

On machines with multiple plane groups (such as the Sun-3/110 and other 
machines using the cgf our(4S) frame buffer), pw_preparesurf ace () will 
correctly set up the enable plane so that the rect you are drawing in is visible. 

If you do not use pw_preparesurf ace (), it is possible that part of the area 
you are drawing on is displaying values from another plane group, so that part of 
your image will be occluded. 

If your application violates window boundaries to put up fullscren menus and 
prompts, it is often desirable to remember the state of the screen before you drew 
on it and then repair it when you are finished. On machines with multiple plane 
groups such as the Sun-3/110 you need to restore the state of the enable plane 
and the bits in the other plane group(s). There are routines to help you do this. 

This routine saves the screen image where you area about to draw: 

Pw_pixel_cache * 
pw_save__pixels (pw, rect) ; 

Pixwin *pw; 

Rect *rect; 

typedef struct pw_pixel_cache { 

Rect rect; 

struct pixrect * plane_group[PIX_MAX_PLANE_GROUPS] ; 

} Pw_pixel_cache; 

pw_save_pixels () tries to allocate memory to store the contents of the pix¬ 
els in rect. If it is unable to, it prints out a message on stderr and returns 
PW_PIXEL_CACHE_NULL. If it succeeds, it returns a pointer to a structure 
which holds the rect rect and an array of pixrects with the values of the pixels 
in rect in each plane group. 
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Restoring Screen Pixels Then, when you have finished fullscreen access, you restore the image which you 

drew over with: 

void 

pw_restore_j?ixels (pw, pc) ; 

Pixwin *pw; 

Pw_pixel__cache *pc; 

pw_restore_pixels () restores the state of the screen where you drew. All 
the information it needs is in the Pw_pixel_cache pointer that 
pw_save_j?ixels () returned. 


Fullscreen Drawing If you use pw_preparesurf ace (), you will be given a homogeneous area 

Operations on which to draw during fullscreen access. However, for applications such as 

adjusting the size of windows (“rubber-banding”), you do not want to obscure 
what is underneath. On the other hand, on a machine with multiple plane groups 
you want your fullscreen access to be visible no matter what plane groups are 
being displayed. 

The following routines perform the same vector drawing, raster operation and 
pixwin copying as their counterparts in Imaging Facilities: Pixwins in the Sun- 
View 1 Programmer’s Guide. The difference is that these routines guarantee that 
the operation will happen in all plane groups so it will definitely be visible on¬ 
screen. 

CAUTION To save a lot of overhead, these routines make certain assumptions which 
must be followed. 


Anyone calling these f ullscreen_pw_* routines must 
o have called f ullscreen__init () 

□ have not done any surface preparation under the pixels affected 

□ have not called pw_lock () 

□ use the fullscreen pixwin during this call 

□ use a PIX_NOT (PIX_DST) operation. 


void 

f ullscreen__pw_vector (pw, xO 
Pixwin *pw; 

int xO, yO, xl, yl, 

void 

fullscreen_pw_write(pw, xw. 


pr, xr. 


Pixwin 

*pw; 

int 

xw, yw, width. 

Pixrect 

*pr; 


yO, xl, yl, op, value); 
op, value; 

yw, width, height, op, 
yr) ; 

height, op, xr, yr; 
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void 

fullscreen_pw_copy(pw, xw, yw, width, height, op, 

pw_src, xr, yr); 

Pixwin *pw, *pw_src; 

int xw, yw, width, height, op, xr, yr; 
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Window Management 


The window management routines provide the standard user interface presented 
by tool windows: 

wmgr_open(framefd, rootfd) 
wmgr_close(framefd, rootfd) 
wmgr_move(framefd) 
wmgr_stretch(framefd) 
wmgr__top (f ramefd, rootfd) 
wmgr_bottom (framefd, rootfd) 
wmgr_refreshwindow(windowfd) 

wmgr__open () opens a frame window from its iconic state to normal size. 
wmgr_close () closes a frame window from its normal size to its iconic size. 
wmgr_move () prompts the user to move a frame window or cancel the opera¬ 
tion. If confirmed, the rest of the move interaction, including dragging the win¬ 
dow and moving the bits on the screen, is done. wmgr_stretch () is like 
wmgr_move (), but it stretches the window instead of moving it. 
wmgr_top () places a frame window on the top of the window stack. 
wmgr_bottom () places the frame window on the bottom of the window stack. 
wmgr_ref reshwindow () causes windowf d and all its descendant windows 
to repaint. 

The routine wmgr_changerect (): 

wmgr_changerect(feedbackfd, windowfd, event, move, noprompt) 
int feedbackfd, windowfd; 

Event *event; 

int move, noprompt; 

implements wmgr_move () and wmgr_stretch (), including the user 
interaction sequence, windowf d is moved (1) or stretched (0) depending on the 
value of move. To accomplish the user interaction, the input event is read from 
the feedbackfd window (usually the same as windowfd). The prompt is 
turned off if noprompt is 1. 
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Tool Invocation 


Utilities 


int 

wmgr_confirm(windowfd, text) 
int windowfd; 
char *text; 

wmgr_conf irm () implements a layer over the prompt package for a standard 
confirmation user interface, text is put up in a prompt box. If the user 
confirms with a left mouse button press, then —1 is returned. Otherwise, 0 is 
returned. The up button event is not consumed. 

NOTE This routine is preserved only for backwards compatibility with versions of the 

SunOS prior to Release 4.0. You should use the new package documented in the 
SunView 1 Programmer’s Guide for dialogs with the user. wmgr_conf irm () 
is not used for user interaction by SunView 1 packages unless the user has dis¬ 
abled Alerts in the Compatibility category of defaultsedit(l). 

wmgr_forktool(programname, otherargs, rectnormal, recticon, 
iconic) 

char *programname, *otherargs; 

Rect *rectnormal, *recticon; 
int iconic; 

is used to fork a new tool that has its normal rectangle set to rectnormal and 
its icon rectangle set to recticon. If iconic is not zero, the tool is created 
iconic, programname is the name of the file that is to be run and otherargs 
is the command line that you want to pass to the tool. A path search is done to 
locate the file. Arguments that have embedded white space should be enclosed 
by double quotes. 

The utilities described here are some of the low level routines that are used to 
implement the higher level routines. They may be used to put together a window 
.management user interface different from that provided by tools. If a series of 
calls is to be made to procedures that manipulate the window tree, the whole 
sequence should be bracketed by win_lockdata () and 
win_unlockdata (), as described in The Window Hierarchy. 

wmgr_completechangerect(windowfd, rectnew, rectoriginal, 

parentprleft, parentprtop) 

int windowfd; 

Rect *rectnew, *rectoriginal; 
int parentprleft, parentprtop; 

does the work involved with changing the position or size of a window’s rect. 
This involves saving as many bits as possible by copying them on the screen so 
they don’t have to be recomputed. wmgr_completechangerect () would 
be called after some programmatic or user action determined the new window 
position and size in pixels, windowfd is the window being changed, 
rectnew is the window’s new rectangle, rectoriginal is the window’s 
original rectangle, parentprleft and parentprtop are the upper-left 
screen coordinates of the parent of windowfd. 
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wmgr_winandchildrenexposed(pixwin, rl) 

Pixwin *pixwin; 

Rectlist *rl; 

computes the visible portion of pixwin—>pw_clipdat a. pwcd_windowf d 
and its descendants and stores it in rl. This is done by any window manage¬ 
ment routine that is going to try to preserve bits across window changes. For 
example, wmgr_completechangerect () calls 

wmgr_winandchildrenexposed ( ) before and after changing the window 
size/position. The intersection of the two rectlists from the two calls are those 
bits that could possibly be saved. 

wmgr_changelevel(windowfd, parentfd, top) 
int windowfd, parentfd; 
bool top; 

moves a window to the top or bottom of the heap of windows that are descen¬ 
dants of its parent, windowfd identifies the window to be moved; parentfd 
is the file descriptor of that window’s parent, and top controls whether the win¬ 
dow goes to the top (TRUE) or bottom (FALSE). Unlike wmgr_top () and 
wmgr_bottom ( ), no optimization is performed to reduce the amount of 
repainting. wmgr_changelevel () is used in conjunction with other window 
rearrangements, which make repainting unlikely. For example, 
wmgr_close () puts the window at the bottom of the window stack after 
changing its state. 

tdefine WMGR_ICONIC WUF_WMGR1 

wmgr_iswindowopen(windowfd) 
int windowfd; 

The user data of windowfd reflects the state of the window via the 
WMGR_ICONIC flag. WUF_WMGR1 is defined in <sunwindow/win_ioctl.h> and 
WMGR_ICONIC is defined in <suntool/wmgr.h> . wmgr_iswindowopen () 
tests the WMGR_ICONIC flag and returns TRUE or FALSE as the window is 
open or closed. 

Note that client programs should never set or clear the WMGR_ICONIC flag. 

The rootf d window maintains a “next slot” position for both normal tool win¬ 
dows and icon windows in its unused iconic rect data. 
wmgr_setrectalloc () stores the next slot data and 
wmgr_getrectalloc ( ) retrieves it: 
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13.1. Minimal Repaint 
Support 

wmgr_setrectalloc(rootfd, tool_left, tool_top, 

icon_left, icon_top) 

int rootfd; 

short tool_left, tool_top, icon_left, icon_top; 

wmgr_getrectalloc(rootfd, tool_left, tool_top, 

icon_left, icon_top) 

int rootfd; 

short *tool_left, *tool_top, *icon_left, *icon_top; 

If you do a wmgr_setrectalloc (), make sure that all the values you are not 
changing were retrieved with wmgr_getrect alloc (). In other words, both 
procedures affect all the values. 

This is an extremely advanced subsection used only for those who might want to 
implement routines similar of the higher level window management routines 
mentioned above. This section has strong connections to the Advanced Imaging 
chapter and the chapter on Rects and Rectlists. Readers should refer to both from 
here. 

Moving windows about on the screen may involve repainting large portions of 
their image in new places. Often, the existing image can be copied to the new 
location, saving the cost of regenerating it. Two procedures are provided to sup¬ 
port this function: 

win_computeclipping(windowfd) 
int windowfd; 

causes the window system to recompute the exposed and damaged rectlists for 
the window identified by windowfd while withholding the SIGWINCH that 
will tell each owner to repair damage. 


win_partialrepair(windowfd, r) 
int windowfd; 

Rect *r; 

tells the window system to remove the rectangle r from the damaged area for the 
window identified by windowfd. This operation is a no-op if windowfd has 
damage accumulated from a previous window database change, but has not told 
the window system that it has repaired that damage. 

Any window manager can use these facilities according to the following strategy: 

□ The old exposed areas for the affected windows are retrieved and cached. 
(pw_exposed()) 

□ The window database is locked and manipulated to accomplish the rear¬ 
rangement. (win_lockdata(), win_remove(), win setlink(), 
win_setrect (), win insert (),...) 

□ The new area is computed, retrieved, and intersected with the old. 
(win_computeclipping(), pw exposed(), 
rl_intersection()) 
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□ Pixels in the intersection are copied, and those areas are removed from the 
subject window’s damaged area. (pw_lock (), pr_copy (), 
win_partialrepair()) 

□ The window database is unlocked, and any windows still damaged get the 
signals informing them of the reduced damage which must be repaired. 
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14.1. Rects 


Macros on Rects 




Rects and Rectlists 


This chapter describes the geometric structures and operations SunView provides 
for doing rectangle algebra. 

Images are dealt with in rectangular chunks. The basic structure which defines a 
rectangle is the Rect. Where complex shapes are required, they are built up out 
of groups of rectangles. The structure provided for this purpose is the 
Rectlist. 

These structures are defined in the header files <sunwindow/rect. h> and 
<sunwindow/rect list. h>. The library that provides the implementation 
of the functions of these data types is part of /usr/lib/libsunwindow. a. 

The rect is the basic description of a rectangle, and there are macros and pro¬ 
cedures to perform common manipulations on a rect. 


♦define coord short 

typedef struct rect { 
coord r_left; 

coord r_top; 

short r_width; 

short r_height; 

} Rect; 

The rectangle lies in a coordinate system whose origin is in the upper left-hand 
comer and whose dimensions are given in pixels. 

The same header file defines some interesting macros on rectangles. To deter¬ 
mine an edge not given explicitly in the rect: 

♦define rect_right(rp) 

♦define rect_bottom(rp) 

Rect *rp; 

returns the coordinate of the last pixel within the rectangle on the right or bottom, 
respectively. 

Useful predicates returning TRUE or FALSE 32 are: 

32 <sunwindow/rect .h> defines bool, TRUE and FALSE if they are not already defined. 
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rect_isnull(r) 
rect_includespoint(r,x,y) 
rect__equal (rl, r2) 

rect__includesrect (rl, r2) 

rect intersectsrect(rl, r2) 


/* r's width or height is 0 
/* (x,y) lies in r 

/* rl and r2 coincide 

* exactly 

/* every point in r2 

* lies in rl */ 

/* at least one point lies 

* in both rl and r2 */ 



*/ 

*/ 

*/ 


Rect *r, *rl, *r2; 
coord x, y; 

Macros which manipulate dimensions of rectangles are: 

rect_construct(r, x, y, w, h) 

Rect *r; 

int x, y, w, h; 

This fills in r with the indicated origin and dimensions. 


rect_marginadjust(r, m) 
Rect *r; 
int m; 


adds a margin of m pixels on each side of r; that is, r becomes 2*m larger in each 
dimension. 


rect_passtoparent(x, y, 
rect_passtochild(x, y, 
coord x, y; 

Rect *r; 


r) 

r) 



sets the origin of the indicated rect to transform it to the coordinate system of a 
parent or child rectangle, so that its points are now located relative to the parent 
or child’s origin, x and y are the origin of the parent or child rectangle within its 
parent; these values are added to, or respectively subtracted from, the origin of 
the rectangle pointed to by r, thus transforming the rectangle to the new coordi¬ 
nate system. 


Procedures and External Data A null rectangle, that is one whose origin and dimensions are all 0, is defined for 
for Rects convenience: 

extern struct rect rect null; 


The following procedures are also defined in rect. h: 

Rect 

rect_bounding(rl, r2) 

Rect *rl, *r2; 

This returns the minimal rect that encloses the union of r 1 and r2. The returned 
value is a struct, not a pointer. 


rect_intersection(rl, r2, rd) 

Rect *rl, *r2, *rd; 

computes the intersection of rl and r2, and stores that rect into rd. 
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14.2. Rectlists 


bool 

rect_clipvector(r, xO, yO, xl, yl) 

Rect *r; 

int *x0, *y0, *xl, *yl; 

modifies the vector endpoints so they lie entirely within the rect, and returns 
FALSE if that excludes the whole vector, otherwise it returns TRUE. 

NOTE This procedure should not be used to clip a vector to multiple abutting rectan¬ 
gles. It may not cross the boundaries smoothly. 

bool rect_order(rl, r2, sortorder) 

Rect *rl, *r2; 
int sortorder; 

returns TRUE if r 1 precedes or equals r 2 in the indicated ordering: 


#define RECTS_TOPTOBOTTOM 0 
#define RECTS_BOTTOMTOTOP 1 
#define RECTS_LEFTTORIGHT 2 
#define RECTS RIGHTTOLEFT 3 


Two related defined constants are: 

#define RECTS_UNSORTED 4 
indicating a “don’t-care” order, and 
#define RECTS_SORTS 4 

giving the number of sort orders available, for use in allocating arrays and so on. 


A Rect list is a structure that defines a list of rects. A number of rectangles 
may be collected into a list that defines an interesting portion of a larger rectan¬ 
gle. An equivalent way of looking at it is that a large rectangle may be frag¬ 
mented into a number of smaller rectangles, which together comprise all the 
larger rectangle’s interesting portions. A typical application of such a list is to 
define the portions of one rectangle remaining visible when it is partially 
obscured by others. 


typedef struct rectlist { 
coord rl_x, rl_y; 

Rectnode *rl__head; 
Rectnode *rl_tail, 
Rect rl_bound; 

} Rectlist; 

typedef struct rectnode { 
Rectnode *rn_next; 
Rect rn_rect ; 

} Rectnode; 


Each node in the rectlist contains a rectangle which covers one part of the visible 
whole, along with a pointer to the next node, r Inbound is the minimal bound¬ 
ing rectangle of the union of all the rectangles in the node list. All rectangles in 
the rectlist are described in the same coordinate system, which may be translated 
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efficiently by modifying rl_x and rl_y. 

The routines that manipulate rectlists do their own memory management on 
rectnodes, creating and freeing them as necessary to adjust the area described by 
the rectlist. 

Macros and Constants 

Defined on Rectlists 

Macros to perform common coordinate transformations are provided: 

rl_rectoffset(rl, rs, rd) 

Rectlist *rl; 

Rect *rs, *rd; 

copies rs into rd, and then adjusts rd’s origin by adding the offsets from rl. 

rl_coordoffset(rl, x, y) 

Rectlist *rl; 
coord x, y; 

offsets x and y by the offsets in r 1. For instance, it converts a point in one of 
the rects in the rectnode list of a rectlist to the coordinate system of the rectlist’s 
parent. 

Parallel to the macros on rect’s, we have: 

rl_passtoparent(x, y, rl) 
rl_passtochild(x, y, rl) 
coord x, y; 

Rectlist *rl; 

which add or subtract the given coordinates from the rectlist’s rl x and rl y 
to convert the rl into its parent’s or child’s coordinate system. 

Procedures and External Data 
for Rectlists 

An empty rectlist is defined, which should be used to initialize any rectlist before 
it is operated on: 

extern struct rectlist rl_null; 

Procedures are provided for useful predicates and manipulations. The following 
declarations apply uniformly in the descriptions below: 

Rectlist *rl, *rll, *rl2, *rld; 

Rect *r; 

coord x, y; 

Predicates return TRUE or FALSE. Refer to the following table for specifics. 
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Table 14-1 Rectlist Predicates 


Macro 

Returns TRUE if 

rl_empty(rl) 

Contains only null rects 

rl_equal(rll, rl2) 

The two rectlists describe the same space identically — 
same fragments in the same order 

rl_includespoint(rl,x,y) 

(x,y) lies within some rect of rl 

rl_equalrect(r, rl) 

rl has exactly one rect, which is the same as r 

rl_boundintersectsrect(r, rl) 

Some point lies both in r and in rl’s bounding rect 


Manipulation procedures operate through side-effects, rather than returning a 
value. Note that it is legitimate to use a rectlist as both a source and destination 
in one of these procedures. The source node list will be freed and reallocated 
appropriately for the result. Refer to the following table for specifics. 


#$un 

\r microsystems 


Revision A, of May 9, 1988 






202 Sun View 1 System Programmer’s Guide 


Table 14-2 Rectlist Procedures 


Procedure 

Effect 

rl_intersection(rll, rl2, rid) 

Stores into rid a rectlist which covers the intersection of 
rll and rl 2 . 

rl_union(rll, rl2, rid) 

Stores into rid a rectlist which covers the union of rll and 
rl2. 

rl difference(rll, rl2, rid) 

Stores into rid a rectlist which covers the area of rll not 
covered by rl 2 . 

rl_coalesce(rl) 

Attempts to shorten rl by coalescing some of its fragments. 
Anri whose bounding rect is completely covered by the 
union of its node rects will be collapsed to a single node; 
other simple reductions will be found; but the general solu¬ 
tion to the problem is not attempted. 

rl_sort(rl, rid, sort) 
int sort; 

rl is copied into rid, with the node rects arranged in sort 
order. 

rl_rectintersection (r, rl, rid) 

rid is filled with a recdist that covers the intersection of r 
and rl. 

rl_rectunion(r, rl, rid) 

rid is filled with a rectlist that covers the union of r and 
rl. 

rl_rectdifference(r, rl, rid) 

rid is filled with a rectlist that covers the portion of rl 
which is not in r. 

rl_initwithrect(r, rl) 

Fills in rl so that it covers the rect r. 

rl_copy(rl, rid) 

Fills in rid with a copy of rl. 

rl free(rl) 

Frees the storage allocated to rl. 

rl_normalize(rl) 

Resets rl’s offsets (rl_x, rl_y) to be 0 after adjusting the 
origins of all rects in rl accordingly. 
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Scrollbars 


Canvases, text subwindows and panels have been designed to work with 
scrollbars. The text subwindow automatically creates its own vertical scrollbar. 
For canvases and panels, it is your responsibility to create the scrollbar and pass 
it in via the attributes WIN_VERTICAL_SCROLLBAR or 
WIN_HORIZONTAL_SCROLLBAR. 

The chapter on scrollbars in the SunView Programmer’s Guide covers what most 
applications need to know about scrollbars. 

The material in this chapter will be of interest only if you are writing an applica¬ 
tion not based on canvases, text subwindows or panels, and you need to com¬ 
municate with the scrollbar directly as events are received. This chapter is 
directed to programmers writing software which receives scroll-request events 
and implements scrolling. 

The definitions necessary to use scrollbars are found in the header file 
<suntool/scrollbar.h> 


15.1. Basic Scrollbar 
Management 

Registering as a Scrollbar The scrollbar receives events directly from the Notifier. The user makes a scroll 

Client request by releasing a mouse button over the scrollbar. The scrollbar’s job is to 

translate the button-up event into a scrolling request event, and send this event, 
via the Notifier, to its client. 

To receive scrolling request events, the client must register itself with the 
scrollbar via the SCROLL_NOTIFY_CLIENT attribute. For example, 
panel_l would register as a client of bar_l with the call: 

r -s 

scrollbar_set(bar_l, SCROLL_NOTIFY_CLIENT, panel_l, 0) ; 

V_ 


NOTE Before registering with the scrollbar, the client must register with the Notifier by 
calling win_register (). 

In most applications, such as the panel example above, the client and the scrol¬ 
ling object are identical. However, they may well be distinct. In such a case, if 
the client wants the scrollbar to keep track of which object the scrollbar is being 
used with, the client has to inform the scrollbar explicitly of the object which is 
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to be scrolled. This is done by setting the SCROLL_OB JECT attribute. 


For example, in the text subwindow package, the text subwindow is the client to 
be notified. Within a given text subwindow there may be many views onto the 
underlying file. Each of these views has its own scrollbar. So each scrollbar 
created by the text subwindow will have the text subwindow as 
SCROLL_NOTIFY_CLIENT and the particular view as SCROLL_OB JECT. So 
to create scrollbars for two views, the text sub window package would call: 


scrollbar_set(bar_l, 

SCROLL_NOTIFY_CLIENT, textsubwindow_l, 
SCROLL_OBJECT, view_l, 

0 ) ; 


scrollbar_set(bar_2, 

SCROLL_NOTIFY_CLIENT, textsubwindow_l, 
SCROLL_OBJECT, view_2, 

0 ) ; 


Keeping the Scrollbar The visible portion of the scrolling object is called the view into the object The 

Informed scrollbar displays a bubble representing both the location of the view within the 

object and the size of the view relative to the size of the object. In order to com¬ 
pute the size and location of the bubble, and to compute the new offset into the 
object after a scroll, the scrollbar needs to know the current lengths of both the 
object and the view. 

The client must keep the scrollbar informed by setting the attributes 
SCROLL_OBJECT_LENGTH and SCROLL_VIEW_LENGTH. There are two 
obvious strategies for when to update this information. You can ensure that the 
scrollbar is always up-to-date by informing it whenever the lengths in question 
change. If this is too expensive (because the lengths change too frequently) you 
can update the scrollbar only when the cursor enters the scrollbar. 

This strategy of updating the scrollbar when it is entered can be implemented as 
follows. When the scrollbar gets a LOC_RGNENTER or L0C_RGNEXIT event, 
it causes the event-handling procedure of its notify client to be called with a 
SCROLL_ENTER or SCROLL_EXIT event. The client then catches the 
SCROLL_ENTER event and updates the scrollbar, as in the example below. 
(Note that the scrollbar handle to use for the scrollbar_set () call is passed 
in as arg). 
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Notify_value 

panel_event_proc(client, event, arg, type) 
caddr__t client; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

{ 

switch (event_id(event)) { 

case SCROLL_ENTER: 

scrollbar_set((Scrollbar)arg, 

SCROLL_OBJECT_LENGTH, current_ob j_length, 
SCROLL_VIEW_START, current_view_start, 

SCROLL_VIEW_LENGTH, current__view_length, 

0 ); 

break; 

} 

} 


The client can interpret the values of SCROLL_OB JECT_LENGTH, 
SCROLL_VIEW_LENGTH and SCROLL_VIEW_START in whatever units it 
wants to. For example, the panel package uses pixel units, while the text subwin¬ 
dow package uses character units. 

Handling the When the user requests a scroll, the scrollbar client’s event-handling procedure 

SCROLL_REQUEST Event gets called with an event whose event code is SCROLL_REQUEST. The event 

proc is passed an argument (arg in the example below) for event-specific data. 

In the case of scrollbar-related events, arg is a scrollbar handle (type 
Scrollbar). As in the example below, the client’s event proc must switch on 
the SCROLL_REQUEST event and call a procedure to actually perform the 
scroll: 

f -—-—s 

Notify_value 

panel_event_proc(panel, event, arg, type) 

Panel panel; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

{ 

switch (event_id(event)) { 

case SCROLL_REQUEST: 

do_scroll(panel, (Scrollbar)arg); 
break; 

} 

} 

V--- - 
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Performing the Scroll 


The new offset into the scrolling object is computed by the Scrollbar Package, 
and is available to the client via the attribute SCROLL_VIEW_START. The 
client’s job is to paint the object starting at the new offset, and to paint the 
scrollbar reporting the scroll, so that its bubble will be updated to reflect the new 
offset. So in the simplest case the client’s scrolling routine would look some¬ 
thing like this: 


f — 

d°_ 

scroll(sb) 



{ 

Scrollbar sb; 



unsigned new_view_start; 




/* paint scrollbar to show bubble in new position */ 
scrollbar_paint(sb); 




/* get new offset into object from scrollbar */ 
new view__start = (unsigned) scrollbar__get (sb. 




SCROLL_VIEW_START) ; 



} 

/* client's proc to paint object at new offset */ 
paint object(sb->object, new_view_start); 




J 


If the client has both a horizontal and a vertical scrollbar, it will probably be 

necessary to distinguish the direction of the scroll, as in: 
-. 

do_scroll(sb) 

Scrollbar sb; 

{ 

/* paint the scrollbar to show bubble in new position */ 
scrollbar_j?aint (sb) ; 

/* get new offset into object from scrollbar */ 

/* 

* pass the new offset and the direction of the scrollbar 

* into the paint function 
*/ 

paint__object (sb->object, 

scrollbar_get(sb, SCROLL_VIEW_START), 
scrollbar_get(sb, SCROLL_DIRECTION)); 

} 

V- 

In order to repaint the screen efficiently, you need to know which bits appear on 
the screen both before and after the scroll, and thus can be copied to their new 
location with pw_copy (). To compute the copyable region you will need, in 
addition to the current offset into the object (SCROLL__VIEW_START ), the 
offset prior to the scroll (SCROLL_LAST_VIEW_START). 

Note: you are responsible for repainting the scrollbar after a scroll, with one of 
the routines described later in Painting Scrollbars . 
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Normalizing the Scroll 


Painting Scrollbars 


15.2. Advanced Use of 
Scrollbars 


The scrollbar package can be utilized in two modes: normalized and un¬ 
normalized. Un-normalized means that when the user makes a scrolling request, 
it is honored exactly to the pixel, as precisely as resolution permits. In normal¬ 
ized scrolling, the client makes an attempt to put the display in some kind of 
"normal form" after the scrolling has taken place. 

To take panels as an example, this simply means that after a vertical scroll, the 
Panel Package modifies the value of SCROLL_VIEW_START so that the highest 
item which is either fully or partially visible in the panel is placed with its top 
edge SCR0LL_MARGIN pixels from the top of the panel. 

Normalization is enabled by setting the SCROLL_NORMALIZE attribute for the 
scrollbar to TRUE, and the SCROLL_MARGIN attribute to the desired margin. 
SCROLL_NORMALIZE defaults to TRUE, and SCROLL_MARGIN defaults to 
four pixels. 

Note that the scrollbar package simply keeps track of whether the scrolls it com¬ 
putes are intended to be normalized or not. The client who receives the scroll- 
request event is responsible for asking the scrollbar whether normalization 
should be done, and if so, doing it. 

After the client computes the normalized offset, it must update the scrollbar by 
setting the attribute SCROLL_VIEW_START to the normalized offset. 

The basic routine to paint a scrollbar is: 

scrollbar_paint(scrollbar); 

Scrollbar scrollbar; 

scrollbar_paint () repaints only those portions of the scrollbar (page but¬ 
tons, bar proper, and bubble) which have been modified since they were last 
painted. To clear and repaint all portions of the bar, use 
scrollbar_paint_clear(). 

In addition, the routines scrollbar_paint_bubble () and 
scrollbar_clear_bubble () are provided to paint or clear the bubble 
only. 

As indicated previously under Performing the Scroll, the client need not be con¬ 
cerned with the details of the scroll request at all — he may simply use the new 
offset given by the value of the SCROLL_VIEW_START attribute. However, the 
client may want to assume partial or full responsibility for the scroll. He may 
compute the new offset from scratch himself, or start with the offset computed by 
the Scrollbar Package and modify it so as not to have text or other information 
clipped at the top of the window (see the preceding discussion under Normalizing 
the Scroll). 

In order to give you complete control over the scroll, attributes are provided to 
allow you to retrieve all the information about the scroll-request event and the 
object’s state at the time of the event The attributes of interest include: 
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Table 15-1 Scroll-Related Scrollbar Attributes 


Attribute 

Value Type 

Description 

S CROL L_LAS T__VI E W_S TART 

int 

Offset of view into object prior to scroll. 

Get only. 

SCROLL_OBJECT 

caddr_t 

pointer to the scrollable object. 

SCROLL_OBJECT_LENGTH 

int 

Length of scrollable object, in client 
units (value must be >= 0). Default: 0. 

SCROLL_REQUEST_MOTION 

Scroll_motion 

Scrolling motion requested by user. 

SCROLL_REQUEST__OFFSET 

int 

Pixel offset of scrolling request into 
scrollbar. Default: 0. 

SCROLL_VIEW_LENGTH 

int 

Length of viewing window, in client units. 

Default: 0. 

SCROLL_VIEW_START 

int 

Current offset into scrollable object, 
measured in client units. 

(Value must be >= 0). Default: 0. 


Types of Scrolling Motion in 
Simple Mode 


There are three basic types of scrolling motion: 

□ SCROLL_ABSOLUTE. This is the “thumbing” motion requested by the user 
with the middle button. You can retrieve the number of pixels into the 
scrollbar of the request (including the page button which may be present) via 
SCROLL_REQUEST_OFFSET. 

□ SCROLL_FORWARD. This is to be interpreted as a request to bring the loca¬ 
tion of the cursor to the top (left, if horizontal). 

□ S CROLL_BACKWARD . This is to be interpreted as a request to bring the top 
(left, if horizontal) point to the cursor. 

The function which implements scrolling may want to switch on the scrolling 
motion, to implement different algorithms for each motion. In the following 
example, do_absolute_scroll (), do_f orward_scroll (), 
do_backward_scroll () and paint_ob ject () are procedures written 
by the client: 
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do_scroll(sb) 

Scrollbar sb; 

{ 

unsigned new_offset; 

Scroll_motion motion; 

motion = (Scroll_motion) scrollbar_get(sb, SCROLL_MOTION); 

switch (motion) { 

case SCROLL__ABSOLUTE: 

new__offset = do_absolute_scroll (sb) ; 
break; 

case SCROLL_FORWARD: 

new_offset = do_forward_scroll(sb); 
break; 

case SCROLL_BACKWARD: 

new_offset = do_backward_scroll(sb); 
break; 

} 

/* tell the scrollbar of the new offset */ 

scrollbar_set(sb, SCROLL_VIEW_START, new_offset, 0); 

/* paint scrollbar to show bubble in new position */ 

scrollbar_jpaint (sb) ; 

/* client's repainting proc */ 

paint_object(scrollbar_get(sb, SCR0LL_0BJECT, 0); 


Types of Scrolling Motion in Internally, the scrollbar package distinguishes nine different types of motion. 

Advanced Mode depending on which mouse button the user pressed, the state of the shift key, and 

the whether the cursor was in the bar, the forward page button or the backward 
page button. Normally, these motions are mapped onto the three basic motions 
described above. In order to perform this mapping, the scrollbar package needs 
to know the distance between lines. You do this by setting the 
SCROLL_LlNE_HEIGHT attribute, as in: 

- ^ 

scrollbar_set(sb, SCROLL_LINE_HEIGHT f 20, 0) ; 

>_ 


NOTE This is the distance, in pixels, from the top of one line to the top of the succeeding 
line. 

The scrollbar package can also be used in advanced mode, in which case the 
mapping described above is not performed — the motion is passed as is to the 
notify proc. This allows you to inteipret each motion exactly as you want. 

The following table gives the nine motions, the user action which generates 
them, and the basic motions which they are mapped onto (if not in advanced 
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mode) 


Table 15-2 Scrollbar Motions 


Motion 


Generated By 


Mapped to 


ABSOLUTE 


POINT_TO_MIN 
MAX_T 0_P 0 1 NT 
PAGE_F ORWARD 
LI NE__F ORWARD 
MIN_TO_POINT 
POINT_TO_MAX 
PAGE_BACKWARD 
LINE BACKWARD 


middle in bar 

left in bar 

shifted left in bar 

middle in page button 

left in page button 

right in bar 

shifted right in bar 

shifted middle in page button 

right in page button 


ABSOLUTE 

FORWARD 

FORWARD 

FORWARD 


FORWARD 

BACKWARD 

BACKWARD 

BACKWARD 

BACKWARD 


To operate in advanced mode you must: 

□ set the attribute SCROLL_ADVANCED_MODE to TRUE. 

□ Switch on the nine motions in the above table. Note: specifically, 
SCROLL_FORWARD and SCROLL_BACKWARD must not appear in your 
switch statement. In other words, for basic mode switch on the three basic 
motions; for advanced mode switch on the nine advanced motions. 
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Writing a Virtual User Input Device 

Driver 


This section describes what a device driver needs to do in order to conform to the 
Virtual User Input Device (vuid) interface understood by SunView. This is not a 
tutorial on writing a device driver; only the vuid related aspects of device driver 
writing are covered. 


A.l. Firm Events 



Firm event Structure 


A stream of firm events is what your driver is expected to emit when called 
through the read () system call. This stream is simply a byte stream that 
encodes Firm_event structures. A firm event is a structure comprising an ID 
which indicates what kind of event it is, the value of the event, and a time when 
this event occurred; it also carries some information that allows the event’s even¬ 
tual consumer to maintain the complete state of its input system. 


The Firm event structure is defined in <sundev/vuid event. h>: 


typedef struct firm event { 


u_short 

u_char 

u_char 

int 

struct timeval 
} Firm event; 


id; 

pair_type; 

pair; 

value; 

time; 


#define FE_PAIR_NONE 0 
#define FE_PAIR_SET 1 
♦define FE_PAIR_DELTA 2 
♦define FE PAIR ABSOLUTE 3 


Here is what the fields in the Firm event mean: 


a id — is the event’s unique identifier. It is either the id of an existing vuid 
event (if you’re trying to emulate part of the vuid) or your one of your own 
creation (see Choosing VUID Events). 

a value — is the event’s value. It is often 0 (up) or 1 (down). For valuators 
it is a 32 bit integer. 



□ 


time — is the event’s time stamp, i.e., when it occurred. The time stamp is 
not defined to be meaningful except to compare with other Firm_event 
time stamps. In the kernel, a call to uniqt ime (), which takes a pointer to 
a struct timeval, gets you a close-to-current unique time. In user 
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process land, a call to gettimeof day(2) gets time from the same source 
(but it is not made unique). 

Pairs This brings us to pair_type and pair. These two fields enable a consumer 

of events to maintain input state in an event-independent way. The pair field is 
critical for a input state maintenance package, one that is designed to not know 
anything about the semantics of particular events, to maintain correct data for 
corresponding absolute, delta and paired state variables. Some examples will 
make this clear: 

□ Say you have a tablet emitting absolute locations. Depending on the client, 
what the absolute location is may be important (say for digitizing) and then 
again the difference between the current location and the previous location 
may be of interest (say for computing acceleration while tracking a cursor). 

□ Say you are keyboard in which the user has typed A C. Your driver first emits 
a SHIFT_CTRL event as the control key goes down. Next your driver emits 
a A C event (one of the events from the ASCII vuid segment) as the c key 
goes down. Now the application that you are driving happens to be using 
the c key as a shift key in some specialized application. The application 
wants to be able to say to SunView (the maintainer of the input state), “Is 
the c key down?” and get a correct response. 

The vuid supports a notion of updating a companion event at the same time that a 
single event is generated. In the first situations above, the tablet wants to be able 
to update companion absolute and relative event values with a single event. In 
the second situations above, the keyboard wants to be able to update companion 
A C and c event values with a single event. The vuid supports this notion of 
updating a companion event in such a way as to be independent from these two 
particular cases. pair_type defines the type of the companion event: 

□ FE_PAIR_NONE — is the common case in which pair is not defined, i.e., 
there is no companion. 

□ FE_PAIR_SET — is used for ASCII controlled events in which pair is 
the uncontrolled base event, e.g., A C and ’c’ or ’C’, depending on the state of 
the shift key. The use of this pair type is not restricted to ASCII situations. 
This pair type simply says to set the pairth event in id’s vuid segment to be 
value. 

□ FE_PAIR_DELTA — identifies pair as the delta companion to id. This 
means that the pairth event in id’s vuid segment should be set to the 
delta of id’s current value and value. One should always create vuid 
valuator events as delta/absolute pairs. For example, the events 
LOCXDELTA and LOC_X_ABSOLUTE are pairs and the events 

LOC Y DELTA and LOC Y AB SOLUTE are pairs. These events are part 
of the standard WORKSTATION DEVID segment that define the distin¬ 
guish primary locator motion events. 

□ FE_PAIR_ABSOLUTE — identifies pair as the absolute companion to 
id. This means that the pairth event in id’s vuid segment should be set 
to the sum of id’s current value and value. One should always create vuid 
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valuator events as delta/absolute pairs. 

As indicated by the previous discussion, pair must be in the same vuid segment 
as id. 

Choosing VUID Events 

One needs to decide which events the driver is going to emit. If you want to 
emulate the Sun virtual workstation then you want to emit the same events as the 
WORKSTATION DEVID vuid segment. A tablet, for example, can emit abso¬ 
lute locator positions LOC X AB SOLUTE and LOC_Y_ABSOLUTE, instead 
of a mouses relative locator motions LOCXDELTA and LOC Y DELTA. 
SunView will uses these to drive the mouse. 

If you have a completely new device then you want to create a new vuid seg¬ 
ment. This is talked about in the workstations chapter of the SunView System 
Programmer’s Guide. 

A.2. Device Controls 

A vuid driver is expected to respond to a variety of device controls. 

Output Mode 

Many of you will be starting from an existing device driver that already speaks 
its own native protocol. You may not want to flush this old protocol in favor of 
the vuid protocol. In this case you may want to operate in both modes. 
VUID*FORMAT ioct Is are used to control which byte stream format that an 
input device should emit. 

#define VUIDSFORMAT _IOW(v, 1, int) 

♦define VUIDGFORMAT _IOR(v, 2, int) 

♦define VUID_NATIVE 0 

♦define VUID_FIRM_EVENT 1 

VUIDSFORMAT sets the input device byte stream format to one of: 

□ VUID_NATIVE — The device’s native byte stream format (it may be vuid). 

□ VUID_FIRM_EVENT — The byte stream format is Firm_events. 

An ermo of ENOTTY or EINVAL indicates that a device can’t speak 

Firm events. 

VUIDSFORMAT gets the input device byte stream format. 

Device Instancing 

VUID*ADDR ioctls are used to control which address a particular virtual user 
input device segment has. This is used to have an instancing capability, e.g., a 
second mouse. One would: 

□ Take the current mouse driver, which emits events in the 

WORKSTATION DEVID vuid segment. 

□ Define a new vuid segment, say LOC2 DEVID. 

□ Add LOC2_X_ABSOLUTE, LOC2_Y_ABSOLUTE, LOC2_X_DELTA 
and LOC2_Y_DELTA to the LOC2_DEVID vuid segment at the same 
offset from the beginning of the segment as LOC X ABSOLUTE, 

LOC_Y_ABSOLUTE, LOC X DELTA and LOC Y DELTA in the 


WORKSTATIONDEVID. 
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□ Command a mouse to emit events using LOC2_DEVID’s segment address 



and the mouse’s original low byte segment offsets. Thus, it would be emit¬ 
ting LOC2_X_DELTA and LOC2_Y_DELTA, which is what your applica¬ 
tion would eventually receive. 

Here is the VUID*ADDR commands common data structure and command 
definitions: 

typedef struct vuid_addr_probe { 
short base; 

union { 

short next; 

short current; 

} data; 

} Vuid_addr_probe; 

♦define VUIDSADDR _IOW(v, 3, struct vuid_addr_probe) 

♦define VUIDGADDR _IOWR(v, 4, struct vuid addr_probe) 

VUIDSADDR is used to set an alternative vuid segment, base is the vuid dev¬ 
ice addr that you are changing. A vuid device addr is the vuid segment id shifted 
into it’s high byte position, data. next is the new vuid device addr that should 
be used instead of base. An ermo of ENOTTY indicates that a device can’t deal 
with these commands. An ermo of ENODEV indicates that the requested virtual 
device has no events generated for it by this physical device. 

VUIDGADDR is used to get an current value of a vuid segment, base is the 
default vuid device addr that you are asking about, data. current is the 
current vuid device addr that is being used instead of base. 

The implementation of these ioctls is optional. If you don’t do it then your 
device wouldn’t be able to support multiple instances. 

Input Controls 

Your device needs to support non-blocking reads in order to run with SunView 
3.0. This means that the read(2) system call returns EWOULDBLOCK when no 
input is available. 

In addition, your driver should support the s elect (2) system call and asynchro¬ 
nous input notification (sending SIGIO when input pending). However, your 
driver will still ran without these two things in 3.0 SunView. 

A.3. Example 

The following example is parts of code taken from the Sun 3.0 mouse driver. It 
illustrates some of the points made above. 


/* Copyright (c) 1985 by Sun Microsystems, Inc. */ 

<elided material> 

#include "../sundev/vuid_event.h" 

/* 

* Mouse select management is done by utilizing the tty mechanism. 

* We place a single character on the tty raw input queue whenever 
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* there is some amount of mouse data available to be read. Once, 

* all the data has been read, the tty raw input queue is flushed. 


* Note: It is done in order to get around the fact that line 

* disiplines don't have select operations because they are always 
expected to be ttys that stuff characters when they get them onto 
a queue. 


Note: We use spl5 for the mouse because it is functionally the 
same as spl6 and the tty mechanism is using spl5. The original 
* code that was doing its own select processing was using spl6. 

*/ 

#define spl_ms spl5 

/* Software mouse registers */ 
struct ms__softc { 

struct mousebuf { 


short 

short 

struct 


mb_size; 
mb_of f ; 
mouseinfo 


/* 

/* 


size (in mouseinfo units) of buf */ 
current offset in buffer */ 


{ 


char 

char 


mi_x, mi_y; 
mi_buttons; 
0x4 /* 

0x2 /* 

0x1 /* 

timeval mi_ 
/* 


#define MS_HW_BUT1 
#define MS_HW_BUT2 
#define MS_HW_BUT3 

struct 

} mb__info[l]; 

} *ms_buf; 

short ms__buf bytes; /* 

short ms_flags; /* 

short ms_oldoff; /* 

short ms_oldoffl; /* 

short ms__readformat; /* 

#define MS_3BYTE_FORMAT VUID_NATIVE /* 

#define MS VUID FORMAT VUID FIRM EVENT /* 


short ms_vuidaddr; 
short ms_vuidcount; 

short ms_samplecount; 

char ms readbuttons; 


/* 

/* 

/* 

/* 


left button position */ 
middle button position */ 
right button position */ 
time; /* timestamp */ 
however many samples */ 

buffer size (in bytes) */ 

currently unused */ 

index into mousebuf */ 

at mi__x, mi_y or mi_buttons. . . */ 

format of read stream */ 

3 byte format (buts/x/y) */ 
vuid Firm_event format */ 
vuid addr for MS_VUID_FORMAT */ 
count of unread firm events */ 
count of unread mouseinfo samples 
button state as of last read */ 


struct 


msdata { 

struct 

struct 


<elided material> 


ms_softc msd_softc; 
tty *msd_tp; 


struct msdata msdata[NMS]; 
struct msdata *mstptomsd(); 

<elided material> 
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/* Open a mouse. Calls sets mouse line characteristics */ 
/* ARGSUSED */ 
msopen(dev, tp) 

dev_t dev; 
struct tty *tp; 

{ 

register int err, i; 

struct sgttyb sg; 

register struct mousebuf *b; 

register struct ms_softc *ms; 

register struct msdata *msd; 

caddr_t zmemall(); 

register struct cdevsw *dp; 


found: 


/* See if tp is being used to drive ms already. */ 
for (i = 0;i < NMS; ++i) 

if (msdata[i].msd_tp == tp) 
return(0); 

/* Get next free msdata */ 
for (i = 0;i < NMS; ++i) 

if (msdata [i] .msd__tp == 0) 
goto found; 

return(EBUSY) ; 


/* 

if 

/* 


(caddr__t) &sg, 0) ) 


(caddr_t)&sg, 0)) 


Open tty */ 

(err = ttyopen(dev, tp) ) 
return(err); 

Setup tty flags */ 
dp = &cdevsw[major(dev)]; 
if (err = (*dp->d_ioctl) (dev, TIOCGETP, 
goto error; 

sg.sg__flags = RAW+ANYP; 
sg.sg_ispeed = sg.sg_ospeed = B1200; 
if (err = (*dp->d_ioctl) (dev, TIOCSETP, 
goto error; 

/* Set up private data */ 
msd = &msdata[i]; 
msd->msd_xnext = 1; 
msd->msd__tp = tp; 
ms = &msd->msd_softc; 

/* Allocate buffer and initialize data */ 
if (ms->ms_buf == 0) { 

ms->ms_buf bytes = MS_BUF_BYTES ; 

b = (struct mousebuf *)zmemall(memall, ms->ms_bufbytes); 
if (b — 0) { 

err = EINVAL; 
goto error; 

) 

b->mb_size = 1 + (ms->ms_bufbytes-sizeof (struct mousebuf)) 
/ sizeof (struct mouseinfo); 

ms->ms_buf = b; 
ms->ms_vuidaddr = VKEY_FIRST; 
msflush(msd); 
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} 

return (0) ; 

error: 

bzero((caddr_t)msd, sizeof (*msd)); 
bzero((caddr_t)ms, sizeof (*ms)); 
return (err); 

} 

/* 

* Close the mouse 
*/ 

msclose(tp) 

struct tty *tp; 

{ 

register struct msdata *msd = mstptomsd(tp); 
register struct ms_softc *ms; 

if (msd == 0) 

return; 

ms = &msd->msd_softc; 

/* Free mouse buffer */ 
if (ms->ms_buf != NULL) 

wmemfree ( (caddr__t)ms->ms_buf, ms->ms_bufbytes) ; 

/* Close tty */ 
ttyclose(tp); 

/* Zero structures */ 

bzero((caddr_t)msd, sizeof (*msd)); 

bzero ( (caddr__t) ms, sizeof (*ms) ) ; 

} 

/* 

* Read from the mouse buffer 
*/ 

msread(tp, uio) 

struct tty *tp; 
struct uio *uio; 

{ 

register struct msdata *msd = mstptomsd(tp); 
register struct ms_softc *ms; 
register struct mousebuf *b; 
register struct mouseinfo *mi; 

register int error = 0, pri f send___event, hwbit; 
register char c; 

Firm_event fe; 

if (msd == 0) 

return(EINVAL); 
ms = &msd->msd_softc; 
b = ms->ms_buf; 
pri = spl_ms(); 

/* 

* Wait on tty raw queue if this queue is empty since the tty is 

* controlling the select/wakeup/sleep stuff. 
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*/ 

while 


} 

while 


(tp->t__rawq.c_cc <= 0) { 

if (tp->t__state&TS_NBIO) { 

(void) splx(pri); 
return (EWOULDBLOCK); 

} 

sleep((caddr_t)&tp->t_rawq, TTIPRI); 

(lerror && (ms->ms_oldoff1 || ms->ms_oldoff 
mi = &b->mb_inf o [ms->rns__oldof f ] ; 
switch (ms->ms_readformat) { 


!= b->mb off)) { 


<elided material> 


case MS_3BYTE_FORMAT: 
break; 


case MS_VUID_FORMAT: 

if (uio->uio_resid < sizeof (Firm_event)) 
goto done; 
send_event = 0; 
switch (ms->ms_oldoff1++) { 

case 0: /* Send x if changed */ 
if (mi->mi_x != 0) { 

fe.id = vuid__id__addr (ms->ms_vuidaddr) | 
vuid_id__of f set (LOC_X_DELTA) ; 
fe.pair_type = FE_PAIR_ABSOLUTE; 
fe .pair = LOC__X__ABSOLUTE; 
fe.value = mi->mi_x; 
send event = 1; 


break; 


case Is /* Send y if changed */ 
if (mi->mi__y != 0) { 

fe.id = vuid_id_addr(ms->ms_vuidaddr) | 
vuid_id_offset(LOC_Y_DELTA); 
fe.pair_type = FE_PAIR_ABSOLUTE; 
fe.pair = LOC_Y_ABSOLUTE; 
fe.value = -mi->mi_y; 
send_event = 1; 

} 

break; 

default:/* Send buttons if changed */ 

hwbit = MS_HW_BUT1 » (ms->ms_oldoff 1 - 3) ; 
if ((ms->ms_readbuttons & hwbit) != 
(mi->mi_buttons & hwbit)) { 

fe.id = vuid__id_addr (ms->ms_vuidaddr) | 
vuid_id_offset( 

BUT(1) + (ms->ms_oldoff1 - 3) ) ; 
fe.pair_type = F E_P AIR_NONE; 
fe.pair = 0; 
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/* Update read buttons and set value */ 
if (mi->mi_buttons & hwbit) { 
fe.value = 0; 

ms->ms__readbuttons | = hwbit; 

} else { 

fe.value = 1; 

ms->ms_readbuttons &= ~hwbit; 

} 

send__event = 1; 

} 

/* Increment mouse buffer pointer */ 
if (ms->ms_oldoff1 == 5) { 

ms->ms_oldof f++; 

if (ms->ms__oldoff >= b->mb_size) 
ms->ms_oldoff = 0; 
ms->ms_oldoff1 = 0; 

} 

break; 


} 

if (send_event) { 

fe.time = mi->mi_time; 
ms->ms_vuidcount—; 

/* lower pri to avoid mouse droppings */ 

(void) splx(pri); 

error = uiomove(&fe f sizeof(fe) f UIO_READ f uio); 
/* spl_ms should return same priority as pri */ 
pri = spl_ms(); 

} 

break; 


/* Flush tty if no more to read */ 

if ((ms->ms_oldoff1 == 0) && (ms->ms_oldoff == b->mb_off)) 
ttyflush(tp, FREAD); 

/* Release protection AFTER ttyflush or will get out of sync with tty */ 
(void) splx(pri); 
return (0); 


/* Mouse ioctl */ 
msioctl(tp, cmd, data, flag) 
struct tty *tp; 
int cmd; 
caddr_t data; 
int flag; 

{ 

register struct msdata *msd = mstptomsd(tp); 

register struct ms_softc *ms; 

int err = 0, num; 

register int buf_off, read_off; 
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Vuid_addr_probe *addr_j?robe ; 

if (msd == 0) 

return(EINVAL); 
ms = &msd->msd_softc; 
switch (cmd) { 
case FIONREAD: 

switch (ms->ms_readformat) { 

case MS_3BYTE__FORMAT: 

Mint *)data = ms->ms_samplecount; 
break; 

case MS_VUID_FORMAT: 

Mint *)data = sizeof (Firm_event) * ms->ms_vuidcount; 
break; 

} 

break; 

case VUIDSFORMAT: 

if (Mint *)data == ms->ms_readformat) 
break; 

ms->ms_readformat = Mint *)data; 

/* 

* Flush mouse buffer because otherwise ms_*counts 

* get out of sync and some of the offsets can too. 

*/ 

msflush(msd); 
break; 

case VUIDGFORMAT: 

Mint *)data = ms->ms__readformat; 
break; 

case VUIDSADDR: 

addr_^probe = (Vuid_addr_probe *)data; 
if (addr_j>robe->base != VKEY__FIRST) { 
err = ENODEV; 
break; 

} 

ms->ms_vuidaddr = addr_jDrobe->data.next; 
break; 

case VUIDGADDR: 

addr_probe = (Vuid_addr_jprobe *)data; 
if (addr__probe->base != VKEY_FIRST) { 
err = ENODEV; 
break; 

} 

addr__probe->data . current = ms->ms_vuidaddr; 
break; 

case TIOCSETD: 

/* 
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* Don't let the line discipline change once it has been set 

* to a mouse. Changing the ldisc causes msclose to be called 

* even if the ldisc of the tp is the same. 

* We can't let this happen because the window system may have 

* a handle on the mouse buffer. 

* The basic problem is one of having anything depending on 

* the continued existence of ldisc related data. 

* The fix is to have: 

* 1) a way of handing data to the dependent entity, and 

* 2) notifying the dependent entity that the ldisc 

* has been closed. 

*/ 

break; 


(<elided material> 

default: 

err = ttioctl(tp, cmd, data, flag); 

} 

return (err); 


msflush(msd) 

register struct msdata *msd; 

{ 

register struct ms_softc *ms = &msd->msd_softc; 
int s = spl_ms(); 

<elided material> 

ttyflush(msd->msd_tp, FREAD); 

(void) splx(s); 

} 

<elided material> 

/* Called with next byte of mouse data */ 

/*ARGSUSED*/ 
msinput (c, tp) 

register char c; 
struct tty *tp; 

{ 

int s = spl5(); 

<elided material> 

/* Place data on circular buffer */ 
if (wake) 

/* Place character on tty raw input queue to trigger select */ 
ttyinput (' \ 0', msd->msd__tp) ; 

(void) splx(s); 

} 
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/* Match tp to msdata */ 
struct msdata * 
mstptomsd(tp) 

struct tty *tp; 


{ 


register i; 


/* Get next free msdata */ 
for (i = 0;i < NMS; ++i) 

if (msdata[i].msd_tp == tp) 
return(&msdata[i]); 

printf("mstptomsd called with unknown tp %X\n", tp) ; 
return(0); 
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B.l. What Is Supported? 


B.2. Library Loading 
Order 

B.3. Shared Libraries vs. 
Shared Text 


Shared Libraries 



Programming Notes 


Here are useful hints for programmers who use SunView. 

In each release, there may be some difference between the documentation and the 
actual product implementation. The documentation describes the supported 
implementation. In general, the documentation indicates where features are only 
partially implemented, and in which directions future extensions may be 
expected. Any necessary modifications to SunView are accompanied by a 
description of the nature of the changes and appropriate responses to them. 

When loading programs, remember to load higher level libraries first, that is, - 

lsuntool -lsunwindow -lpixrect. 

Starting with release 3.2 of SunOS, the tools in SunView were distributed as two 
huge toolmerge files in order to reduce the working set requirements of SunView. 
Instead of having many different programs running, each including its own copy 
of the libsuntool. a, libsunwindow. a and libpixrect. a libraries, 
several copies of one large program would run at once. 

With the advent of shared libraries in SunOS release 4.0, toolmerging is unneces¬ 
sary in most cases. By default, each tool is compiled and linked to use shared 
libraries, so the code of the SunView 1 libraries is still shared. 33 This also has the 
benefit of greatly reducing the size of SunView 1 binaries. Another benefit is 
that programs will automatically benefit from improvements in the SunView 1 
libraries in each release, without recompilation. 

You may find old programs or Makefiles with references to -DMERGE or - 
DSTANDALONE in them. 

Should you want to compile a program with static libraries, just supply the - 
Bstat ic flag to the link editor or C compiler (read the ld(l) man page for 
details). One reason to use static libraries is that it simplifies part of the debug¬ 
ging process. 


33 The standard C library and many others are shared also. 
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B.4. Error Message 
Decoding 


B.5. Debugging Hints 


Disabling Locking 


The default error reporting scheme described in Section 5.12, Error Handling, 
displays a long hexadecimal number which is the ioct 1 number associated with 
the error. You can turn this number into a more meaningful operation name by: 

□ turning the two least significant digits into a decimal number; 

□ searching /usr/include/sunwindow/win_ioctl .h for 
occurrences of this number; and 

□ noting the ioct 1 operation associated with this number. 

This can provides a quick hint as to what is being complained about without 
resorting to a debugger. 

When debugging non-terminal oriented programs in the window system, there 
are some things that you should know to make things easier. 

As discussed mentioned in passing a process receives a SIGWINCH whenever 
one of its windows changes state. In particular, as soon as a frame is shown, the 
kernel sends it a SIGWINCH. When running as the child of a debugger, the 
SIGWINCH is sent to the parent debugger instead of to the tool. By default, dbx 
simply propagates the SIGWINCH to the tool, while adb traps, leaving the tool 
suspended until the user continues from adb. This behavior is not peculiar to 
SIGWINCH: adb traps all signals by default, while dbx has an initial list of sig¬ 
nals (including SIGWINCH) that are passed on to the child process. You can 
instruct adb to pass SIGWINCH on to the child process by typing lc : i 
I Return 1 . lc is the hex number for 28, which is SIGWlNCH’s number. Re¬ 
enable signal breaking by typing lc : 1 1 Return I . You can instruct dbx to trap 
on a signal by using the catch command. 

For further details, see the entries for the individual debuggers in the User’s 
Manual for the Sun Workstation. In addition, ptrace(2) describes the fine 
points of how kernel signal delivery is modified while a program is being 
debugged. 

The two debuggers differ also in their abilities to interrupt programs built using 
tool windows, dbx knows how to interrupt these programs, but adb doesn’t. 
See Signals from the Control Terminal below for an explanation. 

Another situation specific to the window system is that various forms of locking 
are done that can get in the way of smooth debugging while working at low lev¬ 
els of the system. There are variables in the sunwindow library that disable the 
actual locking. These variables can be turned on from a debugger: 
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Table B-l 

Variables for Disabling Locking 

Variable!Action 

int 

pixwindebug 

When not zero this causes the immediate release of the display 
lock after locking so that the debugger is not continually getting 
hung by being blocked on writes to screen. Display garbage can 
result because of this action. 

int 

win_lockdatadebug 

When not zero, the data lock is never actually locked, preventing 
the debugger from being continually hung during block writes to 
the screen. Unpredictable things may result because of this 
action that can’t properly be described in this context. 

int 

win_grabiodebug 

When not zero will not actually acquire exclusive I/O access 
rights so that the debugger wouldn’t get hung by being blocked 
on writes to the screen and not be able to receive input. The 
debugged process will only be able to do normal display locking 
and be able to get input only in the normal way. 

int 

fullscreendebug 

Like win_grabiodebug but applies to the fullscreen access 
package. 




Change these variables only during debugging. You can set them any time after 
main has been called. 

B.6. Sufficient User To use the SunView environment comfortably requires adequate user memory 

Memory for SunView and SunOS, Sun’s operating system. To achieve the best perfor¬ 

mance, you must reconfigure your own kernel, deleting unused device drivers 
and possibly reducing some tuning parameters. The procedure is documented in 
the manual Installing the SunOS. You will be able to reclaim a significant 
amount of usable main memory. 
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B.7. Coexisting with UNIX This section discusses how a SunView tool interacts with traditional UNIX 

features in the areas of process groups, signal handling, job control and terminal 
emulation. If you are not familiar with these concepts, read the appropriate por¬ 
tions (Process Groups, Signals) of the System Services Overview, and the sig- 
nal(3) and tty(4) entries in the SunOS Reference Manual. 

This discussion explicitly notes those places where the shells and debuggers 
interact differently with a tool. 

System calls made by the library code in a tool affect the signals that will be sent 
to the tool. A tool acts like any program when first started: it inherits the process 
group and control terminal group from its parent process. However, when a 
frame is created, the tool changes its process group to its own process number. 
The following sections describe the effects of this change. 

When the C shell (see csh(l)) starts a program, it changes the process group of 
the child to the child’s process number. In addition, if that program is started in 
the foreground, the C shell also modifies the process group of the control termi¬ 
nal to match the child’s new process group. .Thus, if the tool was started from the 
C shell, the process group modification done by window_create () has no 
effect. 

The Bourne Shell (see sh(l)) and the standard debuggers do not modify their 
child’s process and control terminal groups. Furthermore, both the Bourne Shell 
and adb(l) are ill-prepared for the child to perform such modification. They do 
not propagate signals such as SIGINT to the child because they assume that the 
child is in the same control terminal group as they are. The bottom-line is that 
when a tool is executed by such a parent, typing interrupt characters at the parent 
process does not affect the child, and vice versa. For example, if the user types 
an interrupt character at adb while it is debugging a tool, the tool is not inter¬ 
rupted. Although dbx(l) does not modify its child’s process group, it is 
prepared for the child to do so. 

Job Control and the C Shell The terminal driver and C shell job control interact differently with tools. First, 

let us examine what happens to programs using the graphics subwindow library 
package 34 When the user types an interrupt character on the control terminal, a 
signal is sent to the executing program. When the signal is a SIGTSTP, the 
gf xsw library code sees this signal and releases any SunView locks that it might 
have and removes the graphics from the screen before it actually suspends the 
program. If the program is later continued, the graphics are restored to the 
screen. 

However, when the user types the C shell’s stop command to interrupt the exe¬ 
cuting program, the C shell sends a SIGSTOP to the program and the gf xsw 
library code has no chance to clean up. This causes problems when the code has 
acquired any of the SunView locks, as there is no opportunity to release them. 
Depending on the lock timeouts, the kernel will eventually break the locks, but 


Signals from the Control 
Terminal 


Tool Initialization and Process 
Groups 


34 The gfxsubwindow is an out-dated package used only as an example. 
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until then, the entire screen is unavailable to other programs and the user. To 
avoid this problem, the user should send the C shell kill command with the 
—TSTP option instead of using stop. 

The situation for tools parallels that of the gf xsw code. Thus a tool that wants 
to interact nicely with job control must receive the signals related to job control 
>L SIGINT , ( SIGQUIT, and SIGTSTP) and release any locks it has acquired. 
If the tool is later continued, the tool must receive a SIGCONT so that it can 
reacquire the locks before resuming the window operations it was executing. 

The tool will still be susceptible to the same problems as the gf xsw code when 
it is sent a SIGSTOP. 

A final note: the user often relies on job control without realizing it; the expecta¬ 
tion is that typing interrupt characters will halt a program. Of course, even pro¬ 
grams that do not use SunView facilities, such as a program that opens the termi¬ 
nal in “raw” mode, have to provide a way to terminate the program. A program 
using the gf xsw package that reads any input can provide limited job control by 
calling gfxsw_inputinterrupt s. 
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desktop, continued 
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documentation 
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E 
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IM_NEGEVENT, 38 
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fixup, 173 
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changing interrupt user actions, 63 
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non-blocking, 39 
pick mask, 39 
reading, 39 
redirection, 39 

releasing the current event lock, 60 
seizing all, 182 
state, 55 

synchronization, 60, 61 
synchronous, 39 
unencode, 55 
input device 
control, 56 
enumeration, 58 
query, 57 
removal, 57 

setting and initialization, 57 
input focus, 58, 59 

getting the caret event, 59 
keyboard, 58 
restoring the caret, 59 
setting the caret event, 59 
input_imnull (), 38 
input_readevent, 39 
inputmask, 37 
ioctl(2), 91 
ITIMERJREAL, 81 
ITIMER_VIRTUAL, 81 

J 

job control, 232 

K 

KBD_REQUEST, 58 
kernel tuning, 61 

win_disable_shared_locking, 62 
winclistcharsmax, 62 
ws_check_lock, 62 
ws_check_time, 62 
ws_f ast_poll_duration, 62 
ws_fast_timeout, 61 


kernel tuning, continued 
ws_loc_still, 62 
ws_lock__limit, 62 
ws_set_f avor, 62 
ws_slow_timeout, 62 
ws_vq_node_bytes, 61 
keyboard, 56 
focus, 58 

unencoded input, 55 
KIOCTRANS, 55 

L 

LOC_RGNENTER, 24 
LOC_RGNEXIT, 24 

M 

menu, see fullscreen 
mouse, 56 

sample vuid driver, 218 

N 

Notifier, 67, 13 

advanced usage, 67 
client, see client 
client event handlers, 68 
client events, 68 

copy_func () calling sequence, 79 

destroy event delivery time, 80 

error codes, 88 

event delivery time, 77 

exception event handlers, 70 

interaction with various system calls, 91 

interposition, 72 

miscellaneous issues, 91 

notification, 68 

output event handlers, 69 

output events, 69 

posting destroy events, 80 

posting events, 77 

posting events with an argument, 78 

prioritization, 81 

registering an interposer, 72 

release_func () calling sequence, 79 

restrictions, 67, 90, 

safe destruction, 80 

storage management during event posting, 78 
Notifier functions 

notify_client (), 86 
notify_die(), 85 
not if y__event (), 82 
notify_exception (),83 
notify_get__client_func (), 70 
notify_get_destroy_func (), 71 
notify_get_event_func (), 70 
notify_get_exception__func (), 70, 71 
notify_get_input_func (), 70 
not ify_get_itimer__func (), 71 
notify_get_output_func (), 70 
notify_get_prioritizer_func (), 83 
notify_get_scheduler_func (), 87 
notify_get_signal_func (), 71 
notify__get__wait3_func (), 71 
notify_input (), 82 
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Notifier functions, continued 

notify_interpose_destroy__func (), 73 
notify_interpose_event_func (), 72 
notify_interpose_exception__func (), 73 
notify__interpose_input_func (), 72 
notify_interpose_itimer_func (), 73 
notify__interpose_output_func (), 73 
notify_interpose_signal_func (), 73 
notify_interpose_wait3_func (), 73 
notify_itimer (), 83 
notify_next_destroy_func (), 74 
notify_next_event__func (), 72, 74 
notify_next_exception_func (), 74 
notify_next_input_func (), 74 
notify_next_it imer_func (), 74 
notify_next_output_func(), 74 
notify_next_signal_func(), 74 
notify__next_wait3_func (), 74 
notify_output (), 82 
notify_perror (), 89 
notify_post_destroy (), 80, 85 
notify_post_event (), 69, 77 
notify_post_event_and_arg (), 78, 79 
notify_remove (), 87 
notify_remove_destroy_func (), 75 
notify_remove_event_func (), 75 
notify_remove_exception_func (), 75 
notify__remove_input_func (), 75 
notify_remove_itimer_func (), 75 
notify_remove_output_func (), 75 
notify_remove_signal_func (), 75 
notify_remove_wait3_func (), 75 
notify_set_event__func (), 68, 72 
notify_set__exception_func (), 70 
notify_set_output__func (), 69 
notify_set_j?rioritizer_func (), 81 
notify_set__scheduler_func (), 86 
notify_signal (), 83 
notify_start (), 85 
not if y_stop (), 85 
notify_veto_destroy (), 85 
not if y_wait3 (), 83 
Notify_arg, 69, 79 
NOT IF Y_BAD_F D, 70 
NOT IF Y_BAD_I TIMER, 88 
NOT IF Y_BAD_S IGNAL, 88 
NOTIFY_BADF, 88 
NOT I FY_CL IENT_NULL, 86 
Notify_copy, 79 
NOTIFY_COPY_NULL, 79 
NOTIFY_DESTROY_VETOED, 80, 85, 88 
NOTIFY_DONE, 69, 82 
notify_errno, 73, 88 
Notify_error, 88 
Notify_event, 77 
Notify_event_type, 68 
NOTIFYJFUNC_LIMIT, 73, 89 
NOT IF Y_F UNC__NULL, 70, 84 
NOTIFY_I GNORED, 69, 77, 82 
NOT IF Y__I MMEDI ATE, 68, 77 
NOTIFY_INTERNAL_ERROR, 88 
NOTIFY_INVAL, 80, 89 


NOTIFY_N0_C0NDITI ON, 70, 73, 77, 83, 88 
NOTIFY_NOMEM, 88 
NOTIFY_NOT_STARTED, 85, 88 
NOTIFYJDK, 73, 88 
Notify_release, 79 
NOT IFY_RELEASE__NULL, 79 
NOT IF Y_SAFE, 68, 77 
NOTIFY_SRCH, 88 

NOT IFY_UNKNOWN_CLI ENT, 70, 73, 77, 83, 88 

o 

output_f unc (), 69 

P 

PANEL_DEVID, 54 

Paste function-key processing, 104 

pixwin, 13 

closing, 37 
colormap, 16 
colormap segment, 15 
creation, 36 
damage, 176 
damage report, 177 
destruction, 37 
flashing, 37 
locking, 16 
offset control, 178 
opening, 36 
region, 21 

repair of retained pixwin, 177 
repairing damage, 176 
retained, 177 
signals, 176 
SIGWINCH, 176 
surface preparation, 183 
pixwin functions and macros 
pw_close (), 37 
pw_damaged (), 176 
pw_donedamaged (), 177 
pw_exposed(), 173 
pw_get_x_off set (), 178 
pw_get_y_of f set (), 178 
pw_open (), 21, 36 
pw_prepa re surface (), 183 
pw_region (), 21 
pw__repairretained (), 177 
pw_restore_pixels (), 184 
pw__restrict_clipping (), 173 
pw_save_jpixels (), 183 
pw_set_region_rect (), 24 
pw_set_x_of f set (), 178 
pw_set__xy_of f set (), 178 
pw_set_ 3 r_of f set (), 178 
pixwindebug, 230 
prioritizer__func (), 81 
prompt, see fullscreen 
PW__F IXED_I MAGE, 21, 22 
PW_INPUT_DEFAULT, 21, 22 
PW_NO_LOC_AD JUST, 21, 22 
Pw_pixel_cache (), 183 
PW_PIXEL_CACHE_NULL, 183 
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PW_REPAINT_ALL, 21, 22 
PW_RETAIN, 21, 22 

R 

“raw” mode, 233 
readv(2), 91 
rect, 197, 31 

coord type, 197 
Rectlist, 197 

rect and rectlist functions and macros 
rect_bottom (), 197 
rect_bounding (), 198 
rect_clipvector (), 199 
rect_construct (), 198 
rect__equal (), 198 
rect_includespoint (), 198 
rect_includesrect(), 198 
rect_intersection (), 198 
rect_intersectsrect(), 198 
rect_isnull (), 198 
rect_marginadjust (), 198 
rect__order (), 199 
rect_passtochild (), 198 
rect^passtoparent (), 198 
rect_right (), 197 
rl_boundintersectsrect (), 201 
rl_coalesce (), 202 
rl_coordoffset (), 200 
rl_copy (), 202 
rl_difference (), 202 
rl_empty (), 201 
rl__equal (), 201 
rl_equalrect (), 201 
rl_free (),202 
rl_includespoint (), 201 
rl_initwithrect (),202 
rl__inter sect ion (), 202 
rl_normalize (), 202 
rl_null (),200 
rl_passtochild (), 200 
rl_passtoparent (), 200 
rl_rectdifference (), 202 
rl_rectintersection (), 202 
rl_rectoffset 0,200 
rl_rectunion (), 202 
rl_sort (), 202 
rl_union (), 202 
Rect struct, 197 
rect_null, 198 
Rectlist, 199 
rectnode, 200 
RECTS__BOTTOMTOTOP, 199 
RECTS_LEFTTORIGHT, 199 
RE CT S__R IGHTT OLEF T, 199 
RECTS_SORTS, 199 
RE CT S_T OP TOBOT TOM, 199 
RECTS_UNSORTED, 199 
region 

use for tiles, 21 
rlimit(2), 91 
root window 

accessing the root fd, 50 


s 

scheduler_func (), 86 
SCR_EAST, 50 
SCR_NAMESIZE, 48, 57 
SCR_NORTH, 50 
SCR_POSITIONS, 50 
SCR_SOUTH, 50 
SCR_SWITCHBKGRDFRGRD, 48 
SCR_WEST, 50 
screen, 11,47,48, 56 
adjacent, 50 
creating, 48 
destruction, 49 

fullscreen access, see fullscreen 

mouse, 56 

multiple, 50 

positions, 50 

querying, 49 

standard command-line argument parsing, 49 
SCROLL_DEVID, 54 
SCROLL_ENTER, 206 
SCROLL_EXIT, 206 
SCROLL_REQUEST, 207 
scrollbar, 205 

line-by-line scrolling, 211 
scrolling, 208 
updating, 206 
scrollbar attributes 

SCROLL_LAST_VI EW_START, 210 
S CROLL_L I NE__HE IGHT, 211 
SCROLL_MARGIN, 209 
SCROLL_NORMALIZE, 209 
S CROLL_NOTIFY_CL IENT, 205 
SCROLL_OB JECT, 206, 210 
SCROLL_OBJECT_LENGTH, 206, 210 
SCROLL_REQUEST__MOT I ON, 210 
SCROLL_REQUEST_OFFSET, 210 
SCROLL_VI EW_LENGTH, 206, 210 
SCROLL_VI EW_START, 209, 210 
<suntool/scrollbar.h>, 205 
selection callback procedures, 104, 97, 102 
functionjproc, 105,113 
replyjjroc, 113 
reply_proc (), 106 
selection client debugging 

adjusting RPC timeouts, 109 
dumping selection data, 109 
running a test service, 109 
service displays, 109 
tracing request attributes, 123 
selection library data types 
Seln_function, 110 
Seln_function__buffer, 105, 111 
Seln_holder, 110 
Seln_holders_all, 111 
Seln_rank, 110 
Seln_replier_data, 107, 111 
Seln_request, 102, 111 
Seln_requester, 102, 111 
Seln_response, 105, 110 
Seln_result, 110 
Seln_state, 110 
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selection library procedures 

seln_acquire (), 104,112 
seln_ask (), 103, 112 
seln_clear_functions (), 112 
seln_create (), 96, 98,112 
seln_debug (), 113 
seln_destroy (), 97, 113 
seln_done(), 113 

seln__dump_function_buf fer (), 113 
seln_dump__function_key (), 114 
seln_dump__holder (), 114 
seln_dump_rank (), 114 
seln_dump_response (), 114 
seln_dump_result (), 114 
seln_dump_service (), 114 
seln_dump_state (), 115 
seln__figure_response (), 105, 115 
seln_functions_state (), 102, 115 
seln_get_function_state (), 102, 115 
seln__hold_file (), 109, 115 
seln_holder_same_client (), 116 
seln_holder_same_process (), 116 
seln__inform (), 116 
seln_init_request (), 103,117 
seln_inquire (), 117,126 
seln_inquire_all (), 117 
seln_query (), 103, 118, 126 
SELN__REPORT, 118 
seln_report_event (), 102,116 
seln_report_event()" M , 118 
seln__request (), 103, 119 
seln_same_holder (), 119 
seln_secondary_exists (), 106, 119 
seln_secondary_made (), 106, 119 
seln_use_test_service (), 109, 119 
seln_use_timeout (), 109, 120 
seln_yield (), 104 
seln_yield_all (), 120 
selection request, 102, 95 
buffer, 102 
buffer size, 111 
for non-held selection, 108 
initiated by function-key, 104 
long replies, 104, 108 
read procedure, 103 
replier context, 107 
replying, 106 

request attribute definitions, 103 
requester context, 104 
sample program, 104 
unrecognized requests, 104, 108 
selection request attributes, 121 thru 124 
SELN_REQ_BYTESIZE, 122 

SELN_REQ_COMMI T_PEND ING_DELETE, 106, 108, 123 

SELN_REQ_CONTENTS_ASCII, 103, 122 

SELN_REQ_CONTENTS_P IECES, 122 

SELN_REQ_DELETE, 123 

SELN_REQ_END_REQUEST, 107, 124 

SELN_REQ_FAILED, 124 

SE LN_RE Q_F AKE_LE VEL, 123 

SE LN_RE Q_F I LE_N AME, 122 

SELN_REQ_F IRS T, 122 

SE LN_REQ_F I RST_UN IT, 122 

SELN_REQ_LAST, 122 


selection request attributes, continued 
SELN_REQ_LAST_UN IT, 122 
SELN_REQ_LEVEL, 122 
SELN_REQ_RE STORE, 123 
SELN_REQ_SET_LEVEL, 123 
SELN__REQ_UNKNOWN, 124 
SELN_REQ_UNRECOGNIZED, 104 
SELN_REQ_YIELD, 106, 108, 123 
selection response 

SELN_DELETE, 106 
SELN_FIND, 106 
SELN_I GNORE, 105 
SELN_REQUEST, 106 
SELN_SHELVE, 106 
Selection Service, 95,13 
Selection Service 

acquiring selections, 104 
adjusting RPC timeouts, 109 
callback procedures, 97,102,104,112 
caret, 96 
client, 96 
clipboard, 96 

common request attributes, 121 
concepts, 96 

consume-reply procedure, 103 
data definitions, 110 

debugging clients, see selection client debugging 
enumerated types, 110 

function key notifications and processing, 104 

function key transitions, 101,105 

getting the selection’s contents, 102 

header files, 110 

library, 95 

overview, 96 

Primary, 96 

procedure declarations, 112 
protocol example, 97 
releasing selections, 104 
replying to requests, 106 
request, see selection request 
request buffers, 102 
required header files, 110 
running a test service, 109 
sample program, 104 
sample program get_selection, 125 
sample program seln_demo t 128 
sample programs, 125 
Secondary, 96 
selection holder, 96 
selection rank, 96 

selection__svc (1) program, 97 
sending requests to the selection holder, 102 
server process, 95 
shelf, 96 

status display & tracing, 109 
the selection itself, 96 
timeouts, 109 

tracing request attributes, 123 
SELN_CARET, 110 
SELN_CONT INUED, 110 
SELN_DELETE, 110 
selnjdemo example program, 128 
SELN_D I DNT_HAVE, 110 
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SE LN_EX I ST S, 110 

SELN_FAI LED, 110 

SELN_FILE, 110 

SELN_FIND, 110 

SELN_FN_AGAIN, 110 

SELN_FN_ERROR, 110 

SELN_FN_FIND, 110 

SELN_FN_FRONT, 110 

SELN_FN_GET, 110 

SELN_FN_OPEN, 110 

SELN_FN_PROPS, 110 

SE LN_FN_P UT, 110 

SELN_FN_STOP, 110 

SELN_FN_UNDO, 110 

SELN_IGNORE, 110 

SELN_LEVEL_ALL, 124 

SELN_LEVEL_FIRST, 124 

SELN_LEVEL_LINE, 124 

SELN_LEVEL_NEXT, 124 

SELN_LEVEL_PREVIOUS, 124 

SELN_NON_EXIST, 110 

SELN_NONE, 110 

SELN_PRIMARY, 110 

seln_*, see selection library procedures 

SELN_REQ_*, see selection request attributes 

SELN_REQUEST, 110 

SELN_SECONDARY, 110 

SELN_SHELF, 110 

SELN_SHELVE, 110 

SELN_SUCCESS, 110 

SELN_TRACE_ACQUIRE, 123 

SELN_TRACE_DONE, 123 

SE LN_TRACE_HOLD_FILE, 123 

SELN_TRACE_INFORM, 123 

SELN_TRACE_INQUIRE, 123 

SE LN_TRACE_S TOP, 123 

SELN_TRACE_YIELD, 123 

Seln_*, see selection library data types 

SELNJJNKNOWN, 110 

SELN_UNRECOGNIZED, 110 

SELN_UNSPECIFIED, 110 

SELN_WRONG_RAN, 110 

SELN_WRONG_RANK, 110 

set jmp(2), 91 

setpriority(2), 91 

setquota(2), 91 

SIG_BIT, 81 

SIGALRM, 83 

sigblock(2), 91 

SIGCHLD, 83 

SIGIO, 39 

SIGKILL, 49 

sigmask(2), 91 

signal(3), 232 

signal handling, 232 

signal(2), 90 

signal(3), 91 

sigpause(2), 91 


sigstack(2), 91 
SIGTERM, 49, 80 
SIGTSTP, 232 
SIGURG, 70 
sigvec(2), 90, 91 
SIGVTALRM, 83 
SIGWINCH, 42,176,230 
SIGXCPU, 34 
singlecolor, 47 
Sun View 

abstractions/objects, 11 
architecture, 7,12 
changes from 2.0,3 
compatibility with future releases, 3 
environment usage, 42 
introduction, 3 
no more tool merging, 229 
programming notes, 229 
shared libraries, 229 
system model, 11 
what is supported, 229 
SUNVIEWJDEVID, 54 

system calls not to be used under SunView, 91 

T 

terminal emulation, 232 
tile, 21,11 

dynamically changing flags, 23 
extracting data, 23 
laying out, 22 

notification from the Agent, 23 
notifying tiles through the Agent, 24 
overlap, 14 

registering with the Agent, 21 
removing from the Agent, 26 
SunView 1 model, 14 
tool 

iconic flag, 40 
parent, 42 
TOP_DEVID, 54 
TR_UNTRANS_EVENT, 56 
TRUE, 197 
tty(4), 232 

u 

umask(2), 91 
UNIX and SunView, 232 
UNIX system calls and SunView 
close(2), 91 
dup(2), 91 
ioctl(2), 91 
open(2), 29 
readv(2), 91 
rlimit(2), 91 
select(2), 176 
setitimer(2), 91 
set jmp(2), 91 
setpriority(2), 91 
setquota(2), 91 
sigblock(2), 91 
sigmask(2), 91 
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UNIX system calls and SunView, continued 
signal(2), 90 
signal(3), 91 
sigpause(2), 91 
sigstack(2), 91 
sigvec(2), 90, 91 
write(2), 91 

y 

Virtual User Input Device, see vuid 
vuid, 53 

adding a new segment, 55 
choosing events, 217 
device controls, 217 
example code, 218 
firm events, 215 

input device control — see input device, 56 

no missing keys, 55 

pair, 216 

result values, 55 

sample device driver, 218 

segments, 54 

state, 55 

station codes, 54 
writing a vuid driver, 215 
Vuid_addr_jprobe, 218 

< sun dev/vuid__e vent. h>, 55, 215,218 
VUIDFIRMEVENT, 217 
VUID NATIVE, 217 
VUID_SEG_SIZE, 54 
VUIDGADDR, 218 
VUIDGFORMAT, 217 
VUIDSADDR, 218 
VUIDSFORMAT, 217 

w 

we_getgfxwindow (), 41 
we_getparentwindow (), 43 
we_setgfxwindow (), 41 
we_setparentwindow(), 42 
when_hint, 77 

WIN ioctl number error, 43, 230 
win__bell (), 37 
win_compu tec lipping (), 192 
win_copy_event (), 25 
<sunwindow/win_enum.h>, 35 
win__enum_input_device (), 58 
win_enumerate_children (), 35 
win_enumerate_subtree (), 35 
win__error (), 43 
win__errorhandler (), 43 
win__f dtoname (), 30 
win_fdtonumber(), 31 
win_findintersect(), 41 
win_free_event (), 25 
win_get_designee (), 39 
win_get_event_timeout (), 61 
win__get_f d (), 23 
win_get__f lags (), 23 
win_get_focus_event (), 59 


win_get_kbd_focus (), 58 
win_get_kbd_mask (), 39 
win_get_pick_mask (), 39 
win_get_pixwin (), 23 
win_get_swallow_event (), 59 
win_get_tree_layer (), 36 
win_get__vuid__value (), 55 
win_getheight (), 31 
win_getinputcodebit(), 38 
win__getlink (), 33 
win_getnewwindow (), 29 
win_getowner (), 42 
win_getrect (), 31 
win_getsavedrect (), 32 
win_getscreenpositions (), 50 
win__getsize (), 31 
win_getuserflags (),40 
win_getwidth (), 31 
win_grabio (), 182 
win_grabiodebug, 230 
win_init screenf romargv (), 49 
<sunwindow/win_input.h>, 55 
win_insert(), 33 
win_insertblanket(), 41 
win_is_input_device (), 57 
win_isblanket (), 42 
win_lockdata (), 34, 190 
win_lockdatadebug, 230 
WIN__NAMESIZE, 30 
win_nametonumber(), 30 
win_nextfree(), 30 
WIN_NULLLINK, 30, 32 
win_numbertoname (), 30 
win^partialrepair (), 192 
win_j?ost_event (), 25 
win_post_event_arg (), 25 
win_jpost_id (), 24 
win_j?ost_id_and_arg (), 25 
win_refuse_kbd_focus, 58 
win_register (), 21 
win_release_event_lock (), 60 
win__releaseio (), 182 
win_remove (), 34 
win_remove_input_device (), 57 
win__removeblanket (), 42 
win_screendestroy (), 49 
win_s creenget (), 49 
win_screennew (), 48 
win_set_designee (), 39 
win_set__event_timeout (), 61 
win_set_flags (), 23 
win_set_focus_event (), 59 
win__set__input_device (), 57 
win_set_kbd_focus (), 58 
win_set_kbd_mask (), 39 
win_set_pick__mask (), 39 
win_set_swallow__event (), 59 
win_setinputcodebit(), 38 
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win__setkbd (), 56 
win_setlink (), 33 
win_setmouseposition (), 40 
win_setms (), 56 
win__setowner (), 42 
win_setrect(), 31 
win_setsavedrect (), 32 
win_setscreenpositions (), 50 
win__setuserf lag (), 40 
win_setuserf lags (), 40 
win_un lock data (), 34, 190 
win_unregister (), 26 
win_un set input codebit (), 38 
window, 29, 11 
activation, 33 
as device, 29 
as screen, 47 
blanket, 41 
blanket flag, 40 
clipping, 14 
creation, 29 
cursor tracking, 15 
data, 14 
data lock, 34 
database locking, 16 
decoding error messages, 43 
destruction, 29 
device, 13 
display tree, 14, 32 
enumerating offspring, 35 
enumerating the window tree, 36 
enumeration, 35 
environment usage, 41 
errors, 43 
geometry, 31 

hierarchy, see window — display tree 

iconic flag, 40 

identifier conversion, 30 

input, 37 

input events, 15 

locate window, 41 

mouse position, 40 

naive programs, 41 

name, 30 

new, 29 

next available, 30 
null, 30 
number, 30 
owner, 29,42 
parent, 31 
position, 14, 31 
querying size, 31 
reference, 29 
referencing, 30 
saved rect, 32 
screen information, 49 
SIGWINCH, 42 
user data, 40 
user flags, 40 
window driver, 13 
window attributes 
WIN_FD, 29 


window device layer, 7 
window display tree 

SIGXCPU deadlock resolution, 34 

batched updates, 34 

insertion, 33 

links, 32 

removal, 34 

window functions and macros 
window_create, 232 
window_main__loop (), 85 
window management, 189 
minimal repaint, 192 
WINDOW__GFX, 41 
Window_handle, 35 
WINDOW_PARENT, 42 
windowfd, 30 
WL_BOTTOMCHILD, 32 
WL_COVERED, 32 
WL_COVERING, 32 
WL_ENCLOSING, 32 
WL_OLDERSIB, 32 
WL__OLDE ST CHILD, 32 
WL_PARENT, 32 
WLJTOPCHILD, 32 
WL_YOUNGERSIB, 32 
WL_YOUNGESTCHILD, 32 
wmgr_bottom (), 189 
wmgr_changelevel (), 191 
wmgr_changerect(), 189 
wmgr__close (), 189 
wmgr_completechangerect(), 190 
wmgr_confirm(), 190 
wmgr_forktool (), 190 
wmgr_getrectalloc (), 192 
WMGR_I CONIC, 191 
wmgr_iswindowopen (),191 
wmgremove (), 189 
wmgr_open (), 189 
wmgr_ref reshwindow (), 189 
wmgr_setrectalloc (), 192 
wmgr_stretch (), 189 
wmgr_top (), 189 

wmgr_winandchildrenexposed (), 191 
workstation, 53,11 
WORKSTATI ON_DEVI D, 55, 216 
write(2), 91 

ws_* variables, see kernel tuning 
w s__u s r_a s yn c, 63 
WUFJWMGR1, 191 
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What is SunView? 





Introduction 


SunView (Sun Visual/Integrated Environment for Workstations) is a user- 
interface toolkit to support interactive, graphics-based applications running 
within windows. It consists of two major areas of functionality: building blocks 
for output, and a run-time system for managing input. The building blocks 
include four types of windows: 

□ canvases on which programs can draw, 

□ text subwindows with built in editing capabilities, 

□ panels containing items such as buttons, choice items, and analog sliders, 

□ tty subwindows in which programs can be run. 

Canvases, text subwindows, and panels can be scrolled. 

These windows are arranged as subwindows within frames, which are themselves 
windows. Frames can be transitory or permanent. 

Transient interactions with the user can also take place in menus which can 
“pop-up” anywhere on the screen, and in alerts. 

The run-time system is based on a central Notifier in each application which dis¬ 
tributes input to the appropriate window, and a window manager which manages 
overlapping windows, distributing to the appropriate application. 

The exchange of data between applications running in separate windows (in the 
same or separate processes) is facilitated by a Selection Service. 

The Sun implementations of graphics standards — CGI, CORE, GKS — include 
extensions to run within windows. See the SunCGI Reference Manual, the Sun- 
Core Reference Manual, and the SunGKS manual, respectively, for more infor¬ 
mation. 
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4 Sun View 1 Programmer’s Guide 


History 

Release 3.0 


Release 3.2 

Release 3.4 

Release 3.5 

Release 4.0 


SunView first appeared in SunOS Release 3.0. It is an extension and refinement 
of SunWindows 2.0, containing many enhancements, bug fixes and new facilities 
not present in SunWindows. SunView is upward compatible with SunWindows 
— applications originally written under 2.0 can be recompiled and run under 
SunView. 

In Release 3.0, these changes were reflected in a new organization for the Sun¬ 
View documentation. The material on Pixrects from the 2.0 SunWindows Refer¬ 
ence Manual was broken out into a separate document, the Pixrect Reference 
Manual. Two new documents were introduced, the SunView Programmer’s 
Guide and the SunView System Programmer’s Guide. 

The basic SunView interface, intended to meet the needs of simple and 
moderately complex applications, is documented here. This basic interface cov¬ 
ers the functionality of the SunWindows window and tool layers. 

The companion to this document is the SunView System Programmer’s Guide. 

Its contents are a combination of new and old material. Several of its chapters 
document new facilities such as the Notifier, the Selection Service and the 
Defaults Package. Also included is material from the old SunWindows Reference 
Manual which is of interest to implementors of window managers and other 
advanced applications, such as the window manager routines. 

Many bug fixes and performance improvements were made to SunView for 
Release 3.2. This guide was extensively revised and added to for Release 3.2. 

Further bug fixes and enhancements came out with Release 3.4. These were 
documented in the Release 3.4 Manual. 

Release 3.5 brought support for hardware double-buffering under SunView and 
pixrects. 

Release 4.0 brings major enhancements to the SunView user interface — ‘Search 
and Replace’ in text subwindows, shadowed frames, ‘Props’ frame menu item, 
keyboard control of the caret, etc. — without involving major changes to its pro¬ 
grammatic interface. For example, when programs that use text subwindows are 
recompiled, their users will be able to use the new ‘Select Marked Text’ pop-up 
frame. The alerts package is a new package for presenting information to the 
user and allowing him/her to make choices based on it. 

This guide was revised and reprinted again for 4.0. The major changes are the 
addition of a new Alerts chapter and lists of attributes and functions at the begin¬ 
ning of some chapters as well as in the SunView Interface Summary chapter and 
Index. 
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On-Line Help For information on the programmatic interface to the on-line help facilities of the 

Sun386i, see the Sun386i Developer’s Guide. The spot help interface will be 
supported on all Sun woricstations in the next release of SunView. 

Code No Longer Supported Do not use DEFINE_IC0N_FR0M_IMAGE or 

DEFlNE_CURSOR_FROM_lMAGE as these macros may not be supported in 
future releases. Instead, use icon_create () and cursor_create () to 
create the icon or cursor at runtime. icon_create () is described in Chapter 
14, Icons. cursor_create () is described in Chapter 13, Cursors. 

The old SunWindows stacking menu package has been supplanted by the Sun- 
View walking menu package, described in Chapter 12 of this document. You 
should convert your applications to use the menu package, as the old package 
may not be included in future releases. 

The new alerts package, described in Chapter 10, replaces use of the old (undo¬ 
cumented) menu_prompt () routine in situations where programs want to 
force the user to acknowledge a message or make a choice. Alerts are more flexi¬ 
ble and easy-to-use than menu_prompt (), and we strongly encourage you to 
convert to them. Again, the old package may not be included in future releases. 
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The Sun View Model 


This chapter introduces the conceptual model presented by SunView, covering 
such basic concepts as objects, windows and the Notifier. 

It is important that you understand the material in this chapter before you begin 
to write SunView applications. 


2.1. Objects 


SunView is an object-oriented system. Think of SunView objects as visual 


building blocks which you use to assemble the user interface to your application. 
Different types of objects are provided, each with its particular properties; you 
employ whatever type of object you need for the task at hand. 

The most important class of SunView objects are windows. Not all objects are 
windows, however. Other visual objects include cursors, icons, menus and 
scrollbars. 

Technically, an object is a software entity presenting a functional interface. The 
implementation of the object is not exposed; you manipulate an object by passing 
its unique identifier, or handle, to its associated functions. The style of program¬ 
matic interface resulting from this object-oriented approach is outlined in this 


Chapter. 


Figure 2-1 illustrates the different types and classes of SunView objects: 
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The different types of objects are shown in normal font; the classes to which the 
objects belong are labeled in italics — Subwindow, Window, and Object. 

Each object type is described briefly on the next page. 
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Window Objects 


Other Visual Objects 


Window objects include frames and subwindows. Frames contain non¬ 
overlapping subwindows 2 within their borders. Currently, there are four types of 
subwindows provided by SunView: 

□ Panel Subwindow — A subwindow containing panel items. 

□ Text Subwindow — A subwindow containing text. 

a Canvas Subwindow — A subwindow into which programs can draw. 

□ TTY Subwindow — a terminal emulator, in which commands can be given 
and programs executed. 

The distinctions between frames and subwindows are explained in more detail in 
Section 2.3, Windows, later in this chapter. 

The other types of objects, like windows, are displayed on the screen, but they 
differ from windows in that they are less general and more tailored to their 
specific function. They include: 

□ Panel Item — A component of a panel that facilitates a particular type of 
interaction between the user and the application. Panel items can be moved, 
displayed or undisplayed under program control. There are several 
predefined types of items, including buttons, message items, choice items, 
text items and sliders. 

□ Scrollbar — An object attached to and displayed within a subwindow 
through which a user can control which portion of the subwindow’s contents 
are displayed. Both vertical and horizontal scrollbars can be attached to 
panels and canvases. Text subwindows contain vertical scrollbars by default 
(they cannot contain horizontal scrollbars). 

□ Menu — An object through which a user makes choices and issues com¬ 
mands. By convention in SunView, menus pop up when the user presses the 
right mouse button. Like windows, menus appear on the screen when 
needed, and disappear when they have served their purpose. Menus, how¬ 
ever, differ from windows in several ways. First, they are more ephemeral 
— a menu only remains on the screen as long as the menu button remains 
depressed, 3 in contrast to a window, which remains on the screen until the 
user indicates he is done or the controlling program explicitly undisplays it. 
Second, menus are less flexible than windows; they are designed specifically 
to allow the user to choose from among a list of actions. 


~ |c«»r UV.orJ.ihg 


2 It is SunView’s window layout policy that enforces non-overlapping subwindows, not some limitation of 
the system. If you access the window system at a very low level, subwindows can overlap successfully. 

3 The one exception is in the case of stay-up menus, which will appear when you click the RIGHT mouse 
button and disappear when you click it again. 
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□ Alert —a box on the screen which informs the user of some condition. It 
has one or more buttons which the user can push to dismiss the alert or 
choose a means of continuing. Like menus, alerts are ephemeral — they 
disappear as soon as the user pushes a button or otherwise dismisses the 
alert. Visually, they resemble simple panels containing only images, mes¬ 
sages, and buttons. 

□ Pointer — The object indicating the mouse location on the screen. 

□ Icon — a small (usually 64 x 64 pixel) image representing the application. 

The next section gives some examples showing how typical applications make 

use of SunView objects in their user interface. 


2.2. Examples of the use of Figure 2-2 illustrates the mailtool(l), which uses SunView objects to provide 
Objects by a mouse-oriented interface to the SunOS mail(l) program: 

Applications 

Figure 2-2 Mailtool 
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Mailtool consists of a frame containing three subwindows: a text subwindow in 
which the message headers are displayed, a panel containing various panel items 
(mostly buttons) through which the user can give commands to mail, and a text 
subwindow which displays the current message. An additional text subwindow 
and panel (shown in the figure) appear when you press the reply or compose but¬ 
tons. 

The text subwindows contain scrollbars, allowing the user to bring more infor¬ 
mation into view. 

Figure 2-3 illustrates iconedit(l), a simple bitmap editor for generating 
images to be used by SunView applications: 

Figure 2-3 iconedit 
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iconedit consists of a frame and five subwindows. From upper left to lower 
right they are: 

□ a panel containing instructions on how to use the mouse; 
o a small panel for short messages: 

□ a canvas for drawing the image; 

□ a panel containing various items for issuing commands and setting options 
such as the size of the image being drawn, the drawing mode, etc; 

□ A small canvas for viewing the icon or cursor actual size. 
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None of these subwindows may be scrolled. 

In Figure 2-4, the user has pushed the New Mail button, and the program brings 
up a hour glass cursor (in the upper right of the text subwindow) to denote that it 
is retrieving mail: 

Figure 2-4 iconedit-buttons 


committing changes and retrieving new mail 


1 root@sun.com 

2 root@sun.com 

3 spage@polar 

4 tjacobs@snouking 

5 sages@pages 

6 root@sun.com 

7 root@sun.com 

8 spage@omega 


Mon Dec 
Sat Dec 
Frl Dec 
Tue Dec 


7 03:ZB 
5 03:15 
4 15:23 
1 10:40 


Tue Nov 10 15:41 
Mon Oct 19 22:19 
Tue Oct 20 22:21 
Tue Oct 20 13:02 


35/1942 Teen nail 
117/3087 Tech Mall 
43/1516 what size to Import scrol 
40/1816 Casting 

70/2177 Re: new textsw feature 
55/1671 Tech Mall 
141/4393 Tech Mall 
36/1354 Re: Name completion & cmd 


[ Show ")[ Next ")[ Delete j[ Reply j[ComposF) 

[ Save )[ Folder j Flle: +yb1nfo 


[ Mlsc ] [ Coni ) 


I from rootisnall (ion fict 19 22:19:17 1987 

Return-Path: <root@sna11> ] 

Received: from snal 1 .sun.t:om by zorba.sun.com (3.2/SMI-3.2) 

Id AA19735; Mon, 19 Oct 87 22:19:13 PDT 
I Received: by sna11.sun.com (4.0/SMI-3.2) 

Id AA02077; Tue, 20 Oct 87 03:00:09 PDT 
Date: Tue, 20 Oct 87 03:00:09 PDT 
Message-Id: <8710201000.AA02077@sna11.sun.com> 

From: root@sun.com 
Subject: Tech Mall 
Apparently-To: tech-list 
Status: RO 

Sun Tech Mall for Tue Oct 20 03:00:04 PDT 1987 

Requests to receive tech mall should be sent to al1ases@sun. *** 
**** Items you wish to post to tech should be sent to tech@sun. **** 


I Today's Topics: 


mh wizards, anyone? 
console window problem 


Date: Mon, 19 Oct 87 14:54:11 PDT 
From: now1ck1@speed (Bill Nowlckl) 

Subject: mh wizards, anyone? 

I have heard that a feature I added to sendmall for 4.0 causes mh 
to break. I don't use mh, so could someone who knows what It Is 
doing please get In touch with me? I have a feeling It Is using the -t 
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In Figure 2-5, the user has pressed the mouse button over the Folder panel button 
in the panel: 

Figure 2-5 iconedit-menus 






1 rootSsurTcan^^ 

2 rootfisun.cam 

Mon Dec 

Sat Dec 
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40/1816 
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10 15:41 

70/2177 

6 rootdsun.com 

Mon Oct 

19 22:19 

55/1671 

7 root0sun.com 

Tue Oct 

20 22:21 

141/4393 

8 8page0amsga 

Tue Oct 

20 13:02 

36/1354 


Tech Mall 

Tech Mall 
what size to import scrol 
Casting 

Re: neu textsw feature 
Tech Mail 
Tech Mail 

Re: Name completion & and 


f Shout ~)[ Next ][ Delete Reply ][Compose] 


[ Save ][ Foldej ♦ecpspec 



♦SVDOC 

♦SVMN 

♦Teral no logy 

♦bugs 

♦ laff 

♦Motiflor 

♦sunvlew 

♦terminology/* 

♦wnogat 

♦ybinfo 


f Print ~){Heui Hail] 


f Mlsc H "t»one ) 


From rootftsnaif 

Return-Path: <| 

Received: froi 
Id AAll, 

Received: by snail.sun.can (4.0/SMI-3.2; 

Id AA02077 ; Tue, 20 Oct 07 03:00:09 PDT 
Date: Tue, 20 Oct 07 03:00:09 PDT 
Message-Id: <8710201000.AA02077esna11.sun.con> 
Fran: rootesun.com 
Subject: Tech Mall 
Apparently-To: tech-list 
Status: RO 

Sun Tech Mall for Tue Oct 20 03:00:04 POT 1987 


’ Requests to receive tech mall should be sent to allasesQsun. 

* Items you wish to post to tech should be sent to techCsun. •••' 


Today's Topics: 


mh wizards, anyone? 
console window problem 


Date: Mon, 19 Oct 97 14:54:11 PDT 
From: now1ck18speed (8111 Nowlcklj 
Subject: mh wizards, anyone? 

I have heard that a feature I added to sencknall for 4.0 causes mh 
to break. I don't use mh, so could someone who knows what It Is 
doing please get In touch with me? I have a feeling it Is using the -t 


mail tool has displayed a pop-up menu showing names of files which the user 
can insert into the text item File: by selecting a file. The purpose of this menu is 
to keep a current record of the mailfiles that the user has. 
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2.3. Windows 


Frames 


There are two basic classes of windows in SunView: overlapping frames, which 
contain non-overlapping subwindows. This section describes the distinction 
between the two. 


A frame is not useful in itself — its purpose is to bring subwindows of different 
types together into a common framework so they can be operated on as a unit. A 
frame is said to own the subwindows it contains. 

Frames may also own other frames. Thus the basic SunView structure is a 
hierarchy of windows. It could also be viewed as a tree of windows in which the 
non-leaf nodes are frames and the leaf nodes are subwindows. 

The frame at the top of the hierarchy will be referred to in this document as the 
base frame, other frames will be referred to as subframes . 4 Subframes are typi¬ 
cally used to implement pop-ups, which perform auxiliary functions such as 
allowing the user to set options, or displaying help text. 5 

iconedit uses a pop-up for browsing images. When the user presses the but¬ 
ton labeled Browse, iconedit displays a pop-up which consists of a subframe 
containing a single panel subwindow. 

Figure 2-6 illustrates iconedit with its pop-up displayed. 


Figure 2-6 A subframe 



4 Note that while an application will usually be implemented as a single base frame (and its subwindows and 
subframes), it could well include several base frames. 

5 For details on pop-ups, see Section 4.5.1, Pop-ups, in Chapter 4, Using Windows. 
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Figure 2-7 and Figure 2-8 illustrate the structures of iconedit and mail- 
tool as a tree of windows. Frames are shown as rectangles; subwindows as cir¬ 
cles: 


Figure 2-7 Structure of iconedit 



Figure 2-8 Structure ofmailtool 
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Manipulating Frames Via Frames may be manipulated programmatically by setting the frame’s attributes, 

Menus as described in Chapter 4, Using Windows . Each frame also has a menu which 

allows the user to manipulate the frame directly. The frame menu is invoked by 
pressing the RIGHT mouse button on the exposed parts of the frame, which 
include the double lines surrounding the subwindows and the black frame header 
which usually appears at the top of the frame. 

The menus for base frames and subframes differ slightly, as you can see from 
Figure 2-9 and Figure 2-10. The first window shows the base frame menu; the 
second window shows the subframe menu: 

Figure 2-9 Base frame menu 
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Figure 2-10 Subframe menu 
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Subwindows 


Both menus contain the ‘Move’, ‘Resize’, ‘Front’, ‘Back’, and ‘Redisplay’ com¬ 
mands. ‘Move’ allows the user to change the frame’s location. ‘Resize’ allows 
him or her to change the window’s width and height. ‘Front’ causes the frame to 
move in front of the other windows, becoming fully visible on the “surface” of 
the screen, while ‘Back’ does the opposite, moving the frame behind any other 
windows occupying the same portion of the screen. ‘Redisplay’ simply causes 
the window to be displayed again. 

When the user is finished working with a base frame he may want to destroy it 
for good, in which case he would choose ‘Quit’. Or he may want to ‘Close’ the 
frame, with the anticipation of opening it later and continuing work where he left 
off. A base frame in its closed state is represented on the screen as a small (usu¬ 
ally 64 by 64 pixel) icon. The icon is typically a picture indicating the function 
of the underlying application. 

Subframes may not be closed into icons; when the user finishes with a subframe, 
he simply chooses Done from the menu. While not destroying the subframe, this 
causes it to disappear from the screen. 

Subwindows differ from frames in several basic ways. Subwindows never exist 
independently. They are always owned by a frame, and may not themselves own 
subwindows or subframes. While frames can be moved freely around the screen, 
subwindows are constrained to fit within the borders of the frame to which they 
belong. Also in contrast to frames, subwindows are tiled —they may not over¬ 
lap each other within their frame. Within these constraints (which are enforced 
by a run-time boundary manager) subwindows may be moved and resized by 
either a program or a user. 

So far this chapter has discussed the static aspects of the SunView model. The 
section below outlines the system’s model from a dynamic point of view. 
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2.4. Input: The Notifier SunView is a notification-based system. The Notifler acts as the controlling 

entity within a user process, reading UNIX input from the kernel, and formatting 
it into higher-level events, which it distributes to the different SunView objects. 6 

Callback Style of Programming In the conventional style of interactive programming, the main control loop 

resides in the application. An editor, for example, will read a character, take 
some action based on the character, then read the next character, and so on. 
When a character is received that represents the user’s request to quit, the pro¬ 
gram exits. Figure 2-11 illustrates this approach: 


Figure 2-11 Flow of Control in a Conventional Program 

start 



end 


Notification-based systems invert this “straight line” control structure. The main 
control loop resides in the Notifier, not the application. The Notifier reads events 
and notifies, or calls out to, various procedures which the application has previ¬ 
ously registered with the Notifier. These procedures are called notify procs or 
callback procs. This control structure is shown in Figure 2-12. 


6 SunView events are in a form which you can easily use: an ascii key has been pressed, a mouse button has 
been pressed or released, the mouse has moved, the mouse has entered or exited a window, etc. Events are 
described in detail in in Chapter 6, Handling Input. 
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Figure 2-12 Flow of Control in a Notifier-based Program 
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Why a Notification-Based 
System? 


Relationship Between the 
Notifier, Objects, and the 
Application 


For programmers who are not used to it, this callback style of programming takes 
some getting used to. Its big advantage is that it takes over the burden of manag¬ 
ing a complex, event-driven environment. In SunView, an application typically 
has many objects. In the absence of a centralized notifier, each application must 
be responsible for detecting and dispatching events to all the objects in the pro¬ 
cess. With a centralized Notifier, each component of an application receives only 
the events the user has directed towards it. 

It is not necessary for you to interact with the Notifier directly in your applica¬ 
tion. SunView has a two-tiered scheme in which the packages that support the 
various objects — panels, canvases, scrollbars, etc. — interact with the Notifier 
directly, registering their own callback procedures. The application, in turn, 
registers its own callback procedures with the object 

Typically, when writing a SunView application you first create the various win¬ 
dows and other objects you need for your interface, and register your callback 
procedures with the objects. Then you pass control to the Notifier. The work is 
done in the various callback procedures. 

Let’s illustrate the relationship of the Notifier, the SunView objects and the 
application by taking iconedit as an example. Figure 2-13 illustrates how the 
Notifier receives UNIX input and calls back to iconedit ’s subwindows, which 
in turn call back to procedures supplied by iconedit. 
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Figure 2-13 Flow of Input Events in iconedit, a SunView Application 


user types, moves mouse,presses mouse buttons... 
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UNIX events: input on file descriptors 
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The main point of the diagram on the preceding page is to make clear the 
double-tiered callback scheme. How you register the callback procedures will be 
explained in the chapters on panels and canvases. 

One point worth mentioning is the distinction between the “event procedures” for 
the canvases and the “notify procedures” for the panel items. They are all call¬ 
back procedures, but they have different purposes. The canvas’s event procedure 
doesn’t do much work— basically it calls out to the application’s event pro¬ 
cedure each time an event is received. The application sees every event and is 
free to interpret the events however it likes. 

The event procedure for panels, on the other hand, does quite a bit of processing. 
It determines which item should receive the event, and places its own interpreta¬ 
tion on events — the middle mouse button is ignored, left mouse button down 
over an item is interpreted as a “tentative” activation of the item, etc. It does not 
call back to the notify procedure for the item until it receives a left mouse button 
up over the item. So panel item notify procedures are not so much concerned 
with the event which caused them to be called, but with the fact that the button 
was pushed, or a new choice made, etc. 

Calling the Notifier Directly As mentioned previously, for many applications you will not need to call or be 

called by the Notifier directly — the Notifier calls back to the subwindows, 
which in turn call back to your application. 

However, if you need to use signals, or be notified of the death of a child process 
which you have spawned, you do need to call the Notifier directly. 

The Notifier also provides calls which allow you to insert your own routine in the 
event stream ahead of a window. This technique is known as interposition. 

When and how to call the Notifier directly is covered in Chapter 17, The Notifier. 
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Interface Outline 


This chapter outlines the SunView interface, the SunView libraries, header files, 
object handles, attributes and the standard functions applicable to objects of each 
type. 

SunView Libraries The SunView functions that an application calls are mostly in the library file 

/usr/lib/libsuntool. a if you are using the archive libraries and 
/usr/lib/libsuntool. so if you are using the shared libraries. These 
libraries include the code to create and manipulate high-level objects such as 
frames, panels, scrollbars and icons. These packages in turn call routines in 
/usr/lib/libsunwindow.a or/usr/lib/libsunwindow.so to 
create and manipulate windows and interact with the Notifier. These in turn call 
routines in /usr/lib/libpixrect. a or /usr/lib/libpixrect. so 
that do the drawing on the screen. 

NOTE Shared libraries are introduced in 4.0. The main benefit to using shared libraries 
is that the executables are much smaller (for example, 24K instead of 1Mb for 
textedit alone) because the libraries are loaded dynamically at runtime and are 
subsequently shared by other executables. Additionally, when the shared 
libraries are recompiled, new functionality is added, or bug fixes are made, the 
client applications don’t need to be recompiled and linked unless the . so or an 
interface changed. For more information on shared libraries, see Programming 
Utilities and Libraries. 

Compiling SunView Programs To compile a SunView program you must link in these three libraries, and, 

because they are built one on top of another, their order is important. For exam¬ 
ple, to compile a typical SunView application whose source is myprog. c, you 
would type in the command: 



Header Files The basic definitions needed by a SunView application — covering windows, 

frames, menus, icons and cursors — are obtained by including the header file 
<suntool/sunview. h>. Definitions for the other types of object are found 
in their own include files — <suntool/canvas .h>, <suntool/text .h>, 
<suntool/panel. h>, etc. 
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Object Handles When you create a SunView object, the creation function returns a handle for the 

object. Later, when you wish to manipulate the object or inquire about its state, 
you pass its handle to the appropriate function. This reliance on object handles is 
a way of information-hiding. The handles are opaque in the sense that you can’t 
“see through” them to the actual data structure which represents the object. 

Each object type has a corresponding type of handle. The window types of 
Frame, Canvas, Textsw, Tty and Panel are grouped under the type Win¬ 
dow. So, for example, you can declare a panel as either a Panel or a Window, 
whichever is most appropriate. The other object types are Panel_item, Menu, 
Scrollbar, Cursor, and Icon. 

Since C doesn’t have an opaque type, all the opaque data types mentioned 
above are typedef’d to the UNIX type caddr_t (for “character address 
type”), which in turn is typedef’d to char *. 

In addition to the opaque data types, there are several typedef s which refer 
not to pointers but to structs: Event, Pixf ont, Pixrect, Pixwin, Rect, 
and Rectlist. Generally pointers to these structs are passed to SunView func¬ 
tions, so they are declared as Event *, Pixwin *, etc. The reason that the 
is not included in the typedef is that the structs are publicly available, in 
contrast to the object handles, which include the and which refer to structs 
that are not publicly available. 

The SunView data types are summarized in the table beginning on page 324 in 
Chapter 19, SunView Interface Summary. 

Attribute-based Functions A model such as that used by SunView, which is based on complex and flexible 

objects, presents the problem of how the client is to manipulate the objects. The 
basic idea behind the Sim View interface is to present a small number of func¬ 
tions, which take as arguments a large set of attributes. 

For a given call to create or modify an object, only a subset of the set of all appli¬ 
cable attributes will be of interest. So that only the relevant attributes need be 
mentioned, SunView functions make use of variable-length attribute lists. An 
attribute list consists of attribute/value pairs, separated by commas, and ending 
with a zero. 

Each type of object has its own set of attributes. The attributes have prefixes 
which indicate die type of object they apply to, i.e. FRAME_*, TEXTSW_*, 
CANVAS_*, TTY_*, PANEL_*, MENU_*, CURSOR_*, ICON_*, SCROLL_*, 
etc. 

In addition to the sets of attributes applying to each type of object, there is a set 
of window attributes of the form WIN_* which apply to all window objects. 
These are attributes such as WIN_HEIGHT and WIN_WIDTH, which apply to all 
windows regardless of whether they happen to be panels, canvases, etc. 
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Standard Functions 


Example of Sun View-Style 
Programming 


For objects of all types there is a set of standard functions to create and destroy 
the object and to get and set the object’s attributes. 

Window functions are prefixed with window_, yielding 

□ window_create(), 

□ window_get(), 

□ window_set (), and 
a window_destroy(). 

Providing common window functions reduces the complexity of the interface. 
Non-window functions are prefixed with the name of the object. So, to take 
menus as an example, the standard functions are 

□ menu_create(), 

□ menu_get(), 

□ menu_set(), and 

□ menu_destroy(). 


The flavor of the interface is illustrated with the following code fragment, which 
creates a scrollbar with a width of 10 pixels and a black bubble. Later, the 
scrollbar’s width is changed to 20 pixels. Finally, the scrollbar is destroyed: 





\ 


Scrollbar bar; 




bar = scrollbar_create (SCROLL__WIDTH, 10, 



SCROLL BAR COLOR, 

SCROLL_BLACK, 



0); 




scrollbar_set(bar, SCROLL_WIDTH, 

20, 0); 



scrollbar_destroy(bar); 






J 


Note the zero which terminates the attribute lists in the *_create () and 
*_set () calls. The most common mistake in using attribute lists is to forget 
the final zero. This will not be flagged by the compiler as an error, however, it 
will cause SunView to generate a run-time error message. 

Attribute List Size As you can see from the example above, you can specify several attributes in a 

single create () orset() call. The maximum length of attribute lists in Sun- 
View is 250; see Maximum Attribute List Size in Chapter 18, Attribute Utilities. 



Revision A, of May 9, 1988 










30 SunView 1 Programmer’s Guide 


Reserved Namespaces SunView reserves names beginning with the object types, as well as certain other 

prefixes, for its own use. 

The prefixes listed below should not be used by applications in lower, upper, or 
mixed case. 

Table 3-1 Reserved Prefixes 


ACTION_ 

icon_ 

scroll_ 

alert_ 

menu_ 

seln_ 

attr_ 

notify_ 

textsw_ 

canvas_ 

panel_ 

text_ 

cursor_ 

pixrect_ 

toolsw_ 

defaults_ 

pixwin_ 

tool_ 

e i_ 

P r _ 

ttysw_ 

es_ 

pw 

tty_ 

event_ 

rect_ 

window_ 

ev_ 

rl_ 

win_ 

frame_ 
help 

scrollbar_ 

wmgr_ 
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Using Windows 


This chapter describes how to build SunView applications out of frames and 
subwindows. 

The first section presents the basic window routines. Succeeding sections give 
examples, ranging from the simplest possible application to a moderately useful 
file manager. For quick reference, the examples are given in the table below: 

Table 4-1 Window Usage Examples 


Example 

Description 

Illustrates 

Page 

hello j^or Id 

Minimal SunView program. 

Compilation, frames. 

37 

simple jpanel 

Panel w/message and button. 

Basic attributes, panels. 

39 

lister 

Front end to Is 

Panels, tty subwindows. 

42 

filer 

File manager 

Pop-ups, Selection Service. 

44 

image browserl 

Displays images 

Subwindow layout. 

50 

image _browser_2 

Displays images 

Row/column space. 

53 


Summary Listing and Tables To give you a feeling of what you can do with frames and subwindows, the fol¬ 
lowing page lists the available window and frame attributes, functions and mac¬ 
ros. Many attributes are discussed as they occur in the examples, and in other 
chapters (use the Index to check). However, this chapter does not attempt com¬ 
plete coverage of all the attributes. All are briefly described with their arguments 
in the window and frame summary tables in Chapter 19, SunView Interface Sum¬ 
mary: 

□ the Window Attributes table begins on page 379; 

□ the Frame Attributes table begins on page 382; 

□ the Window Functions and Macros table begins on page 384; 

□ the Command Line Frame Arguments table begins on page 386. 
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Window Attributes 

WIN BELOW 

WIN FIT WIDTH 


WIN_PERCENT_WI DTH 

WIN BOTTOM_MARGIN 

WIN_FONT 


WIN_P ICK__INPUT_MASK 

WIN CLIENT DATA 

WIN_GRAB_ALL_INPUT 


WIN_PIXWIN 

WIN COLUMNS 

WIN_HEIGHT 


WIN_RECT 

WIN COLUMN GAP 

WIN_HORIZONTAL_SCROLLBAR 

WIN_RIGHT_MARGIN 

WIN COLUMN_WIDTH 

WI N_I GNORE_KBD_EVENT 


WI N__R I GHT_OF 

WIN CONSUME KBD EVENT 

WIN_I GNORE_KBD_EVENT S 


WIN_ROW_GAP 

WIN CONSUME KBD EVENTS 

WIN_I GNORE_PICK_EVENT 


WIN_ROW_HEIGHT 

WIN CONSUME PICK EVENT 

WIN_IGNORE_PICK_EVENTS 

WIN_ROWS 

WIN CONSUME PICK EVENTS 

WIN_INPUT_DESIGNEE 


WIN_SCREEN_RECT 

WIN CURSOR 

WIN_KBD_FOCUS 


WINJSHOW 

WIN DEVICE_NAME 

WI N__KBD_INPUT_MASK 


WIN__TOP_MARGIN 

WIN DEVICE NUMBER 

WIN LEFT MARGIN 


WINJTYPE 

WIN ERROR MSG 

WIN__MENU 


WI N_VERT I CAL__S CROLLBAR 

WIN_EVENT_PROC 

WIN_MOUSE__XY 


WIN_WIDTH 

WIN_EVENT_STATE 

WIN_NAME 


WIN__X 

WIN_FD 

WIN_OWNER 


WIN_Y 

WIN FIT HEIGHT 

WIN_PERCENT_HEIGHT 




Frame Attributes 

FRAME_ARGS 

FRAME_DEFAULT_DONE_PROC 

FRAME_NO_CONFIRM 

FRAME_ARGC_PTR_ARGV 

FRAME_DONE_PROC 


FRAME_NTH_SUBFRAME 

FRAME BACKGROUND_COLOR 

FRAME_EMBOLDEN_LABEL 


FRAME_NTH_SUBWINDOW 

FRAME_CLOSED 

FRAME_FOREGROUND_COLOR 


FRAME_NTH_WINDOW 

FRAME_CLOSED_RECT 

FRAME_ICON 


FRAME_OPEN_RECT 

FRAME_CMDLINE_HELP_PROC 

FRAME_INHERIT_COLORS 


FRAME_SHOW_LABEL 

FRAME_CURRENT_RECT 

FRAME_LABEL 


FRAME_SUBWINDOWS_ADJUSTABLE 


Window Functions and Macros 

window_bell(win) 


window_ 

get(win, attribute) 

window create(owner, type. 

attributes) 

window_ 

loop(subframe) 

window default event_j?roc (window, event, arg) 

window_ 

main_loop(base_frame) 

window_destroy (win) 


window_ 

read event(window, event) 

window_done(win) 


window_ 

_refuse_kbd__focus (window) 

window__f it (win) 


window_ 

release event lock(window) 

window_fit_height(win) 


window_ 

return(value) 

window_fit_width(win) 


window_ 

set(win, attributes) 
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4.1. Basic Routines 

This section introduces the basic routines for using windows. It explains how to 
create, modify, and destroy windows. 

Creating a Window 

You create all windows with the function: 

Window 

window_create(owner, type, attributes) 

Window owner; 

<windowtype> type; 

<attribute-list> attributes; 

If you recall from Chapter 2, The SuriView Model , a SunView application is 
implemented as a hierarchy of frames. Each frame owns one or more subwin¬ 
dows. The frame at the top of the hierarchy (the base frame) will have a null 
owner. In the above function, the owner parameter is the handle of the window 
to which the window returned by window_c re ate () will belong. The type 
parameter is the type of the new window; for example, FRAME, PANEL, 
TEXTSW, CANVAS, Or TTY. 

A very simple example of this function would be to create a panel belonging to a 
frame called base_f rame, you would use: 

Panel panel; 

window_create(base_frame. Panel, 0); 

Initiating Event Processing 

The window_create () call does not display the frame on the screen. You 
bring it to life after creating a base frame and its subwindows and subframes, by 
calling window__main_loop (base_f rame) . This call displays the frame 
on the screen and begins processing the events by passing control to the Notifier. 
Chapter 2, The SunView Model, gave a brief explanation of the Notifier. 

Keep in mind that subframes are treated different from base frames because they 
are not tied to the base frame that is activated in the window_main_loop () 
call. In addition, if you create a subframe with WIN_SH0W set to TRUE, when 
the user tries to manipulate the subframe ‘garbage’ data will appear on the 
screen. 

Modifying and Retrieving 
Window Attributes 

You modify and retrieve the value of window attributes with the following two 
functions: 

int 

window set(window, attributes) 

Window window; 

<attribute-list> attributes; 

caddr_t 

window_get(window, attribute) 

Window window; 

Window attribute attribute; 
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NOTE If you call window_get () and specify an inappropriate attribute, a zero will 

be returned. For example, a sub frame cannot be closed. Therefore, the call 


window_get ( sub_f rame, FRAME_CLOSED_RECT ) will not work, so the 
value returned will be zero. A segmentation violation will occur if an attempt is 
made to dereference the return value. 

When you get a pointer back from window_get (), the pointer points into a 
private data structure, whose contents may change. 7 


You destroy windows with the following two functions: 


Destroying Windows 


int 

window_destroy(window) 

Window window; 

int 

window_done(window) 

Window window; 

The difference between these two is that window_destroy () destroys only 
window and its subwindows and subframes. window_done (), on the other 
hand, destroys the entire hierarchy to which the subwindow or subframe belongs. 

When window_destroy () is called on a window, the corresponding file 
descriptors cannot be used again until the Notifier is called. The file descriptor 
associated with the window is not reclaimed until the notifier has a chance to dis¬ 
tribute notifications again. 

The way window_destroy () works is that it asks the window owner if it is 
willing to be destroyed. If so, it queues up a notification procedure to destroy the 
window. This delay protects the program from destroying a window that is being 
accessed in the current call stack. You can work around this restriction, assum¬ 
ing you never reference this window again, by calling 
notif y_f lush_pending () after calling window_destroy (). 


7 For most attributes the pointer returned by window_get () points into per-window storage, but for some 
the storage is static, per-process data. These attributes are flagged in the tables Chapter 19, SunView Interface 
Summary. 
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4.2. Example 1— 

hello_world 

In learning a new programming language or environment, it usually helps to 
begin with a small program that simply prints some output. By creating, compil¬ 
ing, loading, and running the program, you will master the mechanical details. 
Here is a small SunView program: 


r A 

♦include <suntool/sunview.h> 

main () 

{ 

Frame frame; 

frame = window_create(NULL, FRAME, 

FRAME LABEL, "hello world", 

0); 

window main loop(frame); 

} 

^_ j 

After you create the above program in a file called hello world. c, you com¬ 
pile it with the command: 

r \ 

% cc -o hello^world hello^wbrld.c -launtool ^-lsunwindow -lpixrect 


Where, 

□ hello_world is the executable output file that will be created 

□ -lsuntool specifies to link with the suntool object library 

□ -lsunwindow specifies to link with the sunwindow object library 

□ -lpixrect specifies to link with pixrect object library 

After you compile the program, type “hello_world”, and the window will come 
up as shown in Figure 4-1 — a single frame with the words “hello world” in the 
frame header: 
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hello 

world 


Figure 4-1 Hello World Window 



This window is “alive” within the SunView user interface; it can be closed, 
moved, resized, hidden, etc. When closed, a default icon is displayed, which 
contains the text from the frame header. 
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4.3. Example 2— The next program is more complex than the first program. It creates a frame that 

simple_panel contains a frame label and a panel that contains a panel button and a message. 

This program also includes an image that appears when the window closes down 
to an icon. Some basic attributes dealing with fonts, icons, help, error messages 
and parsing command-line flags are introduced. 


#include <stdio.h> 

#include <suntool/sunview.h> 
♦include <suntool/panel.h> 
♦include <suntool/icon.h> 

static void quit_proc(); 
Frame frame; 

Panel panel; 

Pixfont *bold; 

Icon icon; 


static short icon_ji.mage [ ] = { 

♦include <images/hello_world.icon> 

}; 

mpr_static(hello_world, 64, 64, 1, icon_image); 

main(argc, argv) 

int argc; char **argv; 

{ 

bold = pf_open("/usr/lib/fonts/fixedwidthfonts/screen.b.12”); 
if (bold — NULL) exit(l); 


icon = icon_create(ICON_IMAGE, &hello_world, 0); 
frame = window_create(NULL, FRAME, 


FRAME_LABEL, 

FRAME_ICON, 

FRAME_ARGS, 

WI N__ERROR_MS G, 

0 ); 


”hello_world_panel", 
icon, 

argc, argv, 

"Can't create window.". 


panel ** window__create (frame, PANEL, WIN_FONT, bold, 0); 


panel__create_item (panel, PANEL_MESSAGE, 

PANEL_LABEL_STRING, "Push button to quit.", 0) ; 
panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Good-bye", 0, 0), 
PANE L_N OTIFY_PROC, quit_proc, 

0 ); 

window_fit(panel); 
window_fit(frame); 
window_main_loop(frame); 


static void 
quit _j?roc () 

{ 

window_set(frame, FRAME_NO_CONFIRM, TRUE, 0); 
window_destroy(frame); 

} 


W sun 

\r microsystems 


Revision A, of May 9, 1988 







40 SunView 1 Programmer’s Guide 


This program creates a frame containing a single panel with a message and a but¬ 
ton: 

Figure 4-2 Hello World Panel 



Some Frame Attributes 


FRAME LABEL 


FRAME ICON 



WIN ERROR MSG 


The features and attributes used in the above program are discussed below. 

The attributes are discussed below in the order that they appear in the above 
panel. 

The string given as the value for FRAME_LABEL will appear in a black frame 
header strip at the top of the frame. If you do not want the label and the frame 
header to appear, then set the attribute FRAME_SHOW_LABEL to FALSE. 

The program used FRAME_iCON to specify the icon to be shown when the frame 
is closed. This is done by first using the macro mpr_static () to define a 
static memory pixrect that contains this data. Where hello_world is the 
name of the pixrect to be defined. The next three arguments specify the width, 
height, and depth of the image. Typically, for an icon, this is 64, 64, and 1. The 
final argument is an array of shorts that contains the bit pattern of the icon image. 
It takes its image from the file 

/usr/include/images/hello_world. icon. This statically defined 
image is passed to icon_create () at runtime. 

The application uses FRAME ARGS 8 to pass command-line arguments given by 
the user to the frame. A set of command line arguments are recognized by all 
frames. These arguments allow the user to control such basic attributes as the 
frame’s dimensions and label and whether the frame’s initial state is open or 
closed, etc. These arguments begin with -W\ for a complete list of them see the 
Command Line Frame Arguments table in Chapter 19, SunView Interface Sum¬ 
mary. 

WlN_ERROR_MSG provides a simple form of error checking. If this attribute is 
not specified, then window_create () will return 0 on failure. If a value for 
WIN_ERROR_MSG is specified and window_create () fails, then it will print 
the error message on stderr and exit with a status of 1. 


8 As an alternative to FRAME ARGS, you can use FRAME_ARGC_PTR_ARGV, which takes a pointer to 
argc, rather than argc itself. This attribute causes window_create () to strip all arguments beginning with 
-W out of argv, and decrement argc accordingly. 
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Panels 

The panel is created by calling window_create () with the previously created 
frame as the owner and PANEL as the window type. 

Fonts 

By default, text in the panel is rendered in the default system font, which 
window_create () obtains by calling pf_default () . 9 The program 
specified a font by first opening the font with pf_open (), and then passing it 
into the panel as WIN_F0NT. 

NOTE In the SunView context, note that setting WIN_FONT is not equivalent to specify¬ 
ing a font at run time with the -Wt command-line argument: -Wt opens the 
default system font, win_font doesn’t. The only window types that currently 
make use of WIN_F0NT to render characters are panels and text subwindows. 

Panel Items 

The panel contains two panel items: the message saying “Push button to quit.” 
and the Good-bye button. They are created with panel_create_item (). 

Notify Procedure 

The concept of callback procedures was introduced in Chapter 2, The SunView 
Model. Callback procedures for panel items are known as notify procedures. 

The program registered its notify procedure quit_proc ( ) with the Quit but¬ 
ton using the attribute PANEL_NOTlFY_PROC. quit_proc ( ) is called when 
the user selects the button. It in turn calls window_dest roy (), which, as 
explained in the earlier subsection on Destroying Windows, causes 
window_main_loop () to return. Before calling window destroy(),it 
disables the standard SunView confirmation by setting the attribute 
FRAME_N0_C0NFIRM for the frame. 

Window Sizing — 

window fit () 

The final feature illustrated by the example is the use of the window_f it () 
macro. This macro causes a window to exactly fit its contents. 

The contents of a panel are its panel items; the contents of a frame are its subwin¬ 
dows. Therfore, the example program calls window_f it () twice, first fitting 
the panel around its two items, then fitting the frame around its panel. 

A window_f it_width () macro and a window_f it_height () macro 
are used to permit adjusting in only one dimension. These correspond to the 
window attributes WIN_FIT_WIDTH and WIN_FIT_HEIGHT. 

Fitting Frames Around 
Subwindows 

* 

Since Release 3.2, if you use window_f it () or its variants for sizing the 
width and height of a frame, you need to be careful that the subwindows have 
some specified size, or they will be shrunk very small by the window fit () 
call. Usually you give a subwindow a fixed size in one or both dimensions, or 
size it to be a percentage of the frame’s size. The default size of a frame is that it 
encloses an area 34 rows by 80 columns in its default font. 


9 For details on fonts see the Pixrect Reference Manual. 
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4.4. Example 3— lister Figure 4-3 illustrates a program to help manage files. The first version simply 

lets the user list files in the current directory, forming a front-end to the ls(l) 
command: 


Figure 4-3 lister 



The tool presents two subwindows. The top subwindow is a control panel with a 
text item. It contains a place to specify the files to be listed, a List button, and a 
Quit button. 

Below the control panel is a tty subwindow. When the user pushes the List but¬ 
ton, the program constructs a command string consisting of the string “Is ”, fol¬ 
lowed by the value of the File: item, followed by a newline, and inputs the com¬ 
mand string to the tty subwindow by calling ttysw_input (). 

The program is listed in its entirety below. 

Notice that the frame, the panel and the tty subwindow are all declared as type 
Window. They could just as well have been declared as type Frame, Panel 
and Tty. 
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♦include <suntool/sunview.h> 

♦include <suntool/panel.h> 

♦include <suntool/tty.h> 

Window frame, panel, tty; 

Panel__item fname_item; 

static void ls_proc(), quit_proc(); 

main (argc, argv) 

int argc; char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "lister", 

0 ); 

panel = window_create(frame, PANEL, 0); 

create j?anel__items (); 

tty = window_create(frame, TTY, 0); 

window_main_loop(frame); 

exit(0); 

} 

• 

create_j>anel_items () 

{ 

fname_item = panel__create__item (panel, P ANEL__TEXT, 
PANEL_LABEL_STRING, "File: ", 

P ANEL_VALUE_D I SPLAY__LENGTH, 55, 

0 ); 

panel_create__item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "List", 5, 0), 
PANEL_N OTIFY_PROC, ls_proc, 

0 ); 

panel_create__item (panel, PANEL__BUTTON, 

PANEL_LABEL__IMAGE, panel_button_image(panel, "Quit”, 5, 0), 
PANEL_NOTIFY_PROC, quit_proc, 

0 ); 

window_fit_height (panel) ; 

} 

static void 

ls_j?roc (/* ARGS UNUSED */) 

{ " 

char cmdstring[256]; 

sprintf (cmdstring, "Is %s\n", panel__get_value (fname__itern) ) ; 
ttysw__input (tty, cmdstring, strlen (cmdstring)); 


static void 

quit_proc(/* ARGS UNUSED */) 

{ 

window_destroy (frame) ; 

} 

v-----> 
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4.5. Example 4 —filer Our next example builds on the simple front end to Is given in the previous 

example to create a more interesting file manipulation tool. This application 
illustrates the use of the text subwindow, the Selection Service, and pop-ups — 
windows that appear on the screen and disappear dynamically during execution 
of a program. 

In appearance, filer is similar to lister, in that it contains a control panel and tty 
subwindow. The user specifies the directory and file, and pushes the List button, 
causing the Is command to be sent to the tty subwindow: 

Figure 4-4 filer 


f i ler 


[List Pi rectory) [Set Is flags') [Edit] [Delete) [Quit) 
Filing Mode: C Use "File:" item 


Directory: /usr/vieu/doc/app/code 
File: *.c 

/usr/vi eui/doc/app/code/confi rm. c 

/usr/view/doc/app/code/dctool.c 
/usr/view/doc/app/code/filer.c 
/usr/view/doc/app/code/font menu.c 
/usr/view/doc/app/code/hello_worId.c 
/usr/view/doc/app/code/image_browser_l.c 
/usr/view/doc/app/code/image_brouser_2 .c 
/usr/view/doc/app/code/1ister.c 
/usr/view/doc/app/code/menugenproc.c 
/usr/view/doc/app/code/resize_demo.c 
/usr/view/doc/app/code/seln_demo,c 
/usr/view/doc/app/code/showcolor .c 
/usr/view/doc/app/code/simple_canvas.c 
/usr/view/doc/app/code/simplempanel.c 
/usr/view/doc/app/code/spheres.c 
/usr/view/doc/app/code/tty_1o.c 
/usr/view/doc/app/code/typein.c 
polar% Q 


There are three new buttons, each of which illustrates a typical use of pop-ups: 

Set Is flags a pop-up property sheet for setting options to Is; 

Edit a pop-up text subwindow for browsing and editing files; 

Delete a pop-up confirmer which forces the user to confirm or cancel. 

The three buttons are discussed in the pages that follow. The discussion makes 
reference to specific routines in the filer program, which is listed in its entirety as 
filer in Appendix A, Example Programs . 
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Pop-ups In SunView, pop-ups are implemented as subframes containing subwindows. 

The subframe, along with its subwindows, is displayed and undisplayed as 
needed. Pop-ups may be displayed in either a blocking or a non-blocking mode. 
Examples of SunView pop-ups include the mailtool’s composition window and 
textedit’s search and replace. 

Pop-up Text Subwindow The Edit button illustrates a non-blocking pop-up. When the user selects a 

filename and presses the button, a pop-up text subwindow containing the file 
appears: 

Figure 4-5 A Pop-up Text Subwindow 


f 1 ler 


[List Directory] [Set Is flags] [Edit] [Delete] [Quit] 
Filing Mode: O Use "File:" item 


D1rectory: /usr/view/doc/app/code 
File: confirm.c 


/usr/view/doc/app/code/confirm.c 
/usr/view/doc/app/code/dctool.c 


/usr 

/usr 

confirm.c ■ 

i——n—r— —. —— — — __ 



/usr 

/usr 

/usr 

V 

#ifndef lint 

static char sccsid[] - "@(#)confirm.c 1.4 87/01/07 Copyr 1 

/usr 


986 Sun Micro"; 

/usr 


#endif 

/usr 


y********************************************************* 

/usr 


/ 

/usr 



/usr 


#include <suntool/sunvieu.h> 

/usr 


#include <suntool/panel,h> 

/usr 

/usr 


static Frame init_confirmer(); 

/usr 


static int confirm(); 

pola 


static void yes_no_ok(); 


▲ 

int 

confirm_yes(message) 


Both the subframe and text subwindow for the pop-up are created at initialization 
time with the calls: 

-—- 

edit_frame = window_create(base_frame, FRAME, 

FRAME_SHOW_LABEL, TRUE, 

0 ) ; 

editsw = window_create(edit_frame, TEXTSW, 0); 

<--- j 


When the user selects the Edit button, the notify procedure edit_proc () is 
invoked. This function first calls the Selection Service to get the name of the file 
the user has selected. 10 
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It then loads the file into the text subwindow, sets the frame header to the 
filename, and displays the frame with these two calls: 


window_set(editsw f TEXTSW_FILE, filename, 0); 

window set(edit_frame, FRAME_LABEL, filename, WIN_SHOW, TRUE, 0); 


Pop-up Property Sheet The property sheet shown in Figure 4-6 is a typical example of a non-blocking 

pop-up. By pushing the Set Is flags button, the user can get a property sheet 
which allows him to set some of the options to the Is command. While the pro¬ 
perty sheet is displayed, the user can continue to interact with the application, 
setting options now and then. The user can cause the pop-up to disappear at any 
time by pushing the Done button, selecting Done from the subframe’s menu, or 
by pressing the SunView function key labelled 1 Open ] . 

Figure 4-6 A Non-blocking Pop-up 


f i ler 



Invoking the ‘Props’ Menu Item Two attributes are used to control whether the ‘Props’ menu item is active or able 

to be invoked in the frame’s menu. The code fragment given below is taken 
from the filer program. 

The FRAME PROP S_ACT ION_PROC attribute specifies which procedure will 
be called when the ‘Props’ menu item is chosen or the [ Props J key is pressed. In 
the code below, FRAME_PROPS_PROC specifies that the procedure 
ls_f lags_proc () is called when the I Props I key is pressed. 
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WIN SHOW 


Pop-up Confirmer 


The FRAME_PROPS_ACTlVE attribute specifies whether the procedure that is 
specified by the FRAME_PROPS_ACTlON_PROC will be called or not If the 
attribute FRAME_PR0PS_ACTIVE is TRUE, then the frame menu will contain 
an un-greyed ‘Props’ menu item. If the attribute FRAME_PROPS_ACTlVE is 
FALSE, then the frame menu will contain a greyed out ‘Props’ menu item. 


/— 


> 


base_frame = window_create(NULL, FRAME, 



FRAME_ARGS, 

argc, argv. 


F RAME_L ABE L , 

"filer”. 


F RAME_P ROP S_AC TI ON_P ROC , 

ls__f lags_proc. 


FRAME PROPS ACTIVE, 

TRUE, 


0); 


s_ 


-j 


The display of a non-blocking pop-up is controlled using the WIN_SH0W attri¬ 
bute. The initialization routine create_ls_flags_popup() creates the 
subframe, panel, and panel items for the property sheet. When the subframe is 
created, WIN_SHOW is FALSE. 11 The notify procedure for the Set Is flags but¬ 
ton, ls_f lags_proc (), simply sets WIN_SH0W to TRUE for the subframe. 12 

When the notify procedure for the List button, ls_proc (), is called, it calls 
compose_ls_options () to construct the appropriate string of flags based 
on the settings of the items in the property sheet. 

Both the property sheet and the editing subwindow described in the preceding 
section are examples of non-blocking pop-ups, in which the application contin¬ 
ues to receive input while the pop-up is displayed. 

Blocking pop-ups differ in that, when displayed, they receive all input directed to 
the screen. Blocking pop-ups are appropriate when you want to force the user to 
confirm or cancel an irreversible operation before changing the application’s 
state in any way. 

Most uses of blocking pop-ups should use the alert package described in Chapter 
10, Alerts. In the example given below, filer uses an alert for the Delete button 
confirmation. However, if you want to use other panel features, or other kinds of 
windows, then you can use window_loop () for the same effect. 

For example, in Figure @NumberOf(alert-win), when the user makes a selection 
and pushes the Quit button, filer displays a pop-up asking for confirmation. All 
input is directed into this confirmer, and the user is forced to either accept the 
deletion by selecting Yes or cancel it by selecting No : 


11 Note that while WIN_SHOW defaults to TRUE for base frames, it defaults to FALSE for subframes. The 
same holds for FRAME_SHOW_LABEL. 

12 Note that the subframe won’t actually be displayed until control is returned to the Notifier. 
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Figure 4-7 Pop-up Confirmer 




List Directory] [Set Is flags) [Edit] [Delete] || 
Filing Mode: 6 Use "File:" item 


jiii 


Directory: 

File: 


/usr/view/1.75/usr/src/usr.bin/sunwindows/suntoo1/examples 


B 


apia% Is 
Makefile 

Makefile.customer 
Makefile.doc 
jiiil Makefile, old 
SCCSG 

addnewtest* | 
addnewtest.c 
animatecolor* 
animatecolor. 
bounce* 
bounce.c 
canvas_input* 

|: canvas.input. c 
| canvas_repaint* 

| canvas.repaint.c 
coloredit* 
coloredit.c 
confirm.c 
apia% [] 



detool* 

dctool.c 

err 

filer* 

filpr 


menugenproc.c 
resize.demo* 
resize.demo.c 
seln_demo* 

"ipln rlpmn r . 


Are you sure you want to Quit? 


Confirml 


[Cane 


icelj 


image _br ows e r _2 * 
image _browser_2. c 
loopback* 
loopback.c 
menugenproc* 


tty.io.c 
typein* 
typein.c 






window_loop The display of a non-blocking pop-up is controlled using the WIN_SH0W attri¬ 

bute. The display of a blocking pop-up, on the other hand, is controlled with the 
two functions window_loop () and window_return (). 

caddr_t 

window_loop(subframe) 

Frame subframe; 


void 

window_return(return_value) 
caddr_t return_value; 

window_loop () causes the pop-up to be displayed and receive all input 
directed to the screen. The call will not return until window_return () is 
called from one of the pop-up’s notify procedures. The value passed to 
window_return () as return_value will be returned by 
window_loop (). Its interpretation is up to the application. That is, it may be 
used to indicate whether the command was confirmed, whether a valid file name 
was entered, and so on. 
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Restrictions on Pop-Up Frames 

There are some restrictions on pop-up frames displayed using 
window_loop(): 

□ You can only have one subwindow in the pop-up frame. 

o The only subwindow types that work properly are canvases and panels. 

These limitations do not apply to non-blocking pop-ups displayed using 
WIN_SHOW. 

Controlling a Pop-up or 

Frame’s Shadowing 

Sun’s convention is that only transient items such as pop-ups have shadows. 
However, using the attribute FRAME_S HOW_S H ADOW you may control the sha¬ 
dowing effect of a frame or a subframe: 

□ If you want your base frame to have a shadow, then set the attribute 
FRAME_SHOW_SHADOW to TRUE. 

□ You may stop a shadow from appearing with a sub_frame during create time 
by setting FRAME_SHADOW to FALSE. 
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4.6. Example 5— Figure 4-8 illustrates how to specify the size and position of subwindows in order 

image_browser_1 to get the layout that you want This application lets the user view the images in 

files generated by iconedit. The user first presses the List button to get a list¬ 
ing. The user then selects a file that contains an image and press the Show but¬ 
ton to view the image: 

Figure 4-8 imagebrowser_1 



This example presents a somewhat more complex subwindow layout: the tty 
subwindow has been moved to the left, the control panel to the upper right, and a 
panel for displaying the image added on the lower right 

Specifying Subwindow Size You can specify the size of a subwindow either in pixels, with WIN_HEIGHT 

and WIN_WIDTH or in terms of rows and columns, with WIN_R0WS and 
WlN_COLUMNS. 13 If its dimensions are not specified, then a subwindow will 
extend in the y direction to the bottom edge, and in the x direction to the right 
edge of the frame. In this case the subwindow’s height and width will have the 
special value WlN_EXTEND_TO_EDGE, 14 and will track the edge of the frame 
at run time, expanding or shrinking appropriately when the user resizes the 
frame. 

Keep in mind that if you alter the size of a frame so that it exactly borders on a 
subwindow by calling window_f it (), the dimension of the subwindow that 
touches the frame will automatically become WIN_EXTEND_TO_EDGE. 


13 Row/column space is discussed in the next example. 

14 It is meaningless to set the width or height of a frame to WIN EXTEND TO EDGE, and it will interfere 
with subwindow behavior. 
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Default Subwindow Layout The default subwindow layout algorithm is simple. The first subwindow is 

placed at the upper left comer of the frame (leaving space for the frame’s header 
and a border). If the width of the previously-created subwindow is fixed, not 
extend-to-edge, then the next subwindow is placed to the right of it. If the width 
of the previously-created subwindow is extend-to-edge, then the next subwindow 
is placed below it, at the left of the frame. 

Explicit Subwindow Layout This default layout algorithm handles only veiy simple topologies. Sun View 

provides attributes that allow you to specify more complex layouts by explicitly 
positioning subwindows. You can position one subwindow relative to another by 
using WIN_BEL0W and win_RIGHT_OF. These attributes take as their value 
the handle of the subwindow you want the new subwindow to be below or to the 
right of. 

image_browser_l , pictured on the preceding page, illustrates the use of 
window_f it ( ) along with explicit subwindow positioning to obtain a particu¬ 
lar layout. The relevant calls are shown below: 

' -> 

tty = window_create(frame, TTY, 

WIN_ROWS, 20, 

WIN_COLUMNS, 30, 

0 ); 

control_panel = window_create(frame, PANEL, 0); 

(create panel items...) 
window_fit (control_j?anel) ; 

display_panel = window_create(frame, PANEL, 

WIN_BELOW, control__panel, 
WIN_RIGHT_OF, tty, 

0 ); 

window_fit (frame) ; 

<_____y 


First the tty subwindow is created with a fixed height and width. Then the con¬ 
trol panel is created, with no specification of origin or dimensions. 

Since the width of the previous subwindow was fixed, the control panel is placed 
by default just to the right. After its items are created, the control panel is shrunk 
around its items in both dimensions with window_f it (). 

Next, the display panel is created and explicitly positioned below the control 
panel and to the right of the tty subwindow. Both dimensions of the display 
panel default to win_extend_to_edge. 

Finally, window_f it () is called to shrink the frame to the height of the tty 
window and the combined width of the tty window and the control panel. 15 


15 window_fit () causes the window to shrink until it encounters the first fixed border. Subwindows 
which are extend-to-edge don’t stop the shrinking. 
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NOTE One thing to watch out for is that WIN_BEL0W only affects the subwindow’s y 

dimension, and WIN_RIGHT_OF only effects the x dimension. 

You can also specify the origin of a subwindow in pixels using WIN_X and 
WIN_Y. The computations for these attributes take the borders and header of the 
frame into account, so that specifying WIN_X and WIN_Y of 0 will then result in 
the subwindow being placed correctly at the upper left comer of the frame. 

The program resize demo, listed in Appendix A, uses these attributes to lay out 
its subwindows in a non-standard manner. 

If you programmatically change the size or position of subwindows after you 
create them, then you must explicitly re-specify the origin of any subwindows 
that are below or to the right of the altered subwindows. This must be done even 
if you specified the positions of these other subwindows using relative position 
attributes, such as win_below. 

This step is necessary because subwindows are not automatically laid out again 
when the positions and sizes of other subwindows are changed. They are only 
laid out again if the frame changes size. When re-specifying the layout of the 
other subwindows, you can use relative position attributes such as WlN_BELOW. 

The Rect Structure The attributes WIN_X, WIN_Y, WIN_WIDTH and WIN_HEIGHT, taken together, 

define the rectangle occupied by a window. This rectangle is actually stored as a 
Rect struct, which you can get or set using the attribute WIN_RECT. The 
definition of a Rect, found in <sunwindow/rect. h>, is: 16 

typedef struct rect { 
short r_left; 
short r_top; 
short r_width; 
short r_height; 

} Rect; 

The Rect is the basic data structure used in SunView window geometry. Where 
complex shapes are required, they are built up out of groups of rectangles. 17 


Changing Subwindow Layout 
Dynamically 


Specifying Subwindow Sizes 
and Positions 


16 The result that a window returns is relative to a frame’s positioning space. It is not self-relative and it is 
not parent-relative. Therefore, WIN RECT should only be used for window positioning operations. Do not use 
itforpw_lock (). 

17 For a detailed discussion of rectangle geometry, including useful macros for operating on rectangles, see 
the chapter entitled Reds and Rectlists in the SunView 1 System Programmer s Guide. 
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4.7. Example 6— 

image browser_2 


In the next example, when the user specifies a filename and pushes Browse the 
images in the files are displayed in a scrollable panel: 


Figure 4-9 imagebrowser_2 



The point of this example is to illustrate how you can use row!column space to 
specify the size of a subwindow. The goal was to make the panel just the right 
size to display a single page of icons, with four rows, four columns, and 10 pixels 
of white space around each icon. 

Row/Column Space Row/column space refers to a logical grid defining the rows and columns of a 

window. You can define the row/column space for a window by using the attri¬ 
butes in the following table: 

Table 4-2 Window Row!Column Geometry Attributes 


Attribute 

Description 

Default 

Def. in Panels 

WIN_BOTTOM_MARGIN 

Bottom margin. 

0 

(same) 

WIN_COLUMN_GAP 

Space after columns. 

0 

(same) 

WIN_COLUMN_WIDTH 

Width of a column. 

Width of WINJFONT. 

(same) 

WIN_LEFT_MARGIN 

Left margin. 

5 

4 

WIN_RIGHT_MARGIN 

Right margin. 

5 

0 

WIN_ROW_GAP 

Space after rows. 

0 

5 

WIN_ROW_HEIGHT 

Height of a row. 

Height of WIN FONT 

(same) 

WIN_TOP_MARGIN 

Top margin. 

5« 

4 


19 In frames with headers, the default for WIN TOP MARGIN depends on the system font With the default 
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Defining a Panel’s Row/Column Using the row/column space attributes, the icon browsing panel pictured on the 
Space preceding page is specified as follows: 


r 



> 


Scrollbar scrollbar = scrollbar__c reate (SCROLL_MARGIN, 10 f 0) ; 



bar_width = (int)scrollbar_get(scrollbar, SCROLL_THICKNESS, 

0); 


display_panel = window_create(base_ 

frame, PANEL, 



WIN VERTICAL_SCROLLBAR, scrollbar. 



WI N__ROW_HE IGHT, 

64, 



WIN_COLUMN_WIDTH, 

64, 



WIN_ROW_GAP, 

10, 



WIN_COLUMN_GAP, 

10, 



WIN_LEFT_MARGIN, 

bar_width + 10, 



WIN_TOP_MARGIN, 

10, 



WIN_ROWS, 

4, 



WIN COLUMNS, 

4, 



0); 




window_set (display_j?anel, WIN_LEFT_ 

MARGIN, 10, 0); 


V. 



__ -J 


This achieves our goal of a panel the right size for a 4x4 array of 64 pixel square 
icons, with 10 pixels of white space around each icoa 


Positioning Panel Items in Once you have defined your row/column space, you can position panel items 

Row/Column Space within that space with the ATTR_ROW () and ATTR__COL () macros. 20 The code 

fragment shown below shows how the items for the browsing panel are created 
and positioned at the proper row and column each time the Browse button is 
pushed: 


f 


\ 

for (row 

= 0, image count * 0; image_count < files_count; row++) 

for 

(col = 0; col <= 4 && image_count 

< files count; col++) { 

if 

(image = get_image(image_count)) 

{ 


panel_create_item(display_panel, 

PANEL_MESSAGE, 


PANEL__ITEM_Y, 

ATTR_ROW(row), 


PANE L__I TEM_X, 

ATTR_COL(col) , 


PANEL_LABEL_IMAGE, image, 0); 

} 

image_count++; 


} 


-J 


This example is complicated somewhat by an inconsistency in the way margins 
are handled in the current release of SunView. The left and top margins are used 
in two ways: for determining the size of the panel, and for determining the loca¬ 
tion of panel items positioned with ATTR_COL () and ATTR_ROW (). The size 
computation does not take into account any scrollbar which may be present; the 
positioning computation, on the other hand, does take the scrollbar into account 
That is why, in the call to window_create () above, WIN_LEFT_MARGIN is 
set to the width of the scrollbar plus 10 pixels, and then set immediately after¬ 
ward to 10 pixels. 

system font, it defaults to 17. 

20 These “character unit macros** are described fully in Chapter 18, Attribute Utilities. 



Revision A, of May 9,1988 








Chapter 4 — Using Windows 55 


4.8. Attribute Ordering 


Command-line Arguments 


The general rule is that attributes in SunView are evaluated in the order they are 
given. The following two examples of text subwindow calls illustrate how giv¬ 
ing the same attributes in different orders can produce different effects: 


window_set(textsw, TEXTSW_FILE, "file_l", 0); 

window_set(textsw, TEXTSW_FIRST, 20, TEXTSW_FILE, "file_2", 0) ; 


window_set(textsw, TEXTSW_FILE, "file_l", 0); 

window_set(textsw, TEXTSW_FILE, "file_2", TEXTSW_FIRST, 20, 0) ; 


In the first pair of calls, the index is first set to the 20th character of f ile_l, 
then f ile_2 is loaded, starting at character zero. The second pair of calls first 
loads file 2, then sets the index in file 2 to 20. 


The attribute FRAME_ARGS bears special mention. As described in the second 
example in this chapter, simple_panel, this attribute causes the frame to process 
the command-line arguments given by the user at run time. Some of these argu¬ 
ments correspond to attributes that can be set programmatically; for example, - 
wh corresponds to win_rows. 21 

The basic rule, that attributes are evaluated in the order given, applies equally to 
attributes that are explicitly specified in the program and to those that are 
specified at run time using their command-line equivalents. If a given attribute is 
specified more than once, then the last setting is the one that takes effect. You 
can therefore control whether your application or the user has the last word by 
specifying attributes after or before FRAME_ARGS. 

Let’s take a couple of examples: 

window_create(0, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "LABEL FROM PROGRAM", 

WIN_ROWS, 10, 

0 ); 


window_create(0, FRAME, 

FRAME_LABEL, 

WIN_ROWS, 

FRAME_ARGS, 

0 ); 


"LABEL FROM PROGRAM", 

10 , 

argc, argv. 


Assume that the program was invoked with a command line containing the fol¬ 
lowing arguments: 

-Wl "LABEL FROM COMMAND-LINE" -Wh 4 


In the first call, by putting FRAME_ARGS at the start of the list, the application 
overrides the command-line arguments, and guarantees that the frame header will 
read “LABEL FROM PROGRAM” and the height will be 10 lines. 


21 For a complete list of these arguments see the Command Line Frame Arguments table in Chapter 19, 
SunView Interface Summary. 



Revision A, of May 9, 1988 





56 SunView 1 Programmer’s Guide 


Different Classes of Attributes 


The Panel Package 


In the second call, since frame_args appears at the end of the list, the 
command-line arguments override what the application has specified, resulting in 
a label of “LABEL FROM COMMAND-LINE” and a height of 4 lines. 

Keep in mind that if you specify WIN_F0NT, it does not override the font that 
the user specified using -Wt. 

In the case of different objects, the window attributes (those beginning with 
WIN_) are processed after the others (FRAME_*, PANEL_*, and so on). 

Suppose that you want to create a canvas with a scrollbar. You also want the 
logical canvas to expand when the user makes the window bigger, but never to 
shrink past its initial size, even if the user shrinks the window. The initial size of 
the canvas should be the size of the “inner” portion of the window — not includ¬ 
ing the scrollbar. 


The straightforward approach would be to simply set all relevant attributes when 
the window is created, as in: 


canvas 

= window_create(frame, CANVAS, 

WIN_VERTICAL_SCROLLBAR, 

scrollbar_ 

\ 

create(0) , 

V 

CANVAS AUTO SHRINK, 

0); 

FALSE, 



This call, however, results in a canvas which is too big, extending underneath the 
vertical scrollbar. This is because of the order in which the CANVAS_ and WIN_ 
attributes are evaluated. 


Since the window attributes are evaluated after the canvas attributes, the canvas 
size is set according to the initial size of the window, which does not have a 
scrollbar. By the time WIN_VERTICAL_SCROLLBAR is evaluated, the canvas 
refuses to shrink to the smaller inner portion of the window, since 
CANVAS_AUTO_SHRINK has already been evaluated and set to FALSE. 

In general, you can force a particular order of evaluation by using separate 
window_set () calls, as in: 

- > 

canvas *= window_create(frame, CANVAS, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create(0), 
0 ); 

window set(canvas, CANVAS_AOTO_SHRINK, FALSE, 0); 


The panel package deviates from the norm in that its attributes are generally not 
order-dependent. For example, you can specify the label of an item before the 
font, and the font will be used even though it appears after the label. 

The only thing to watch out for is that you can’t change the font in a single call, 
as in: 


»sun 
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/— 



\ 


panel_set (text_item. 




PANEL_FONT, 

font_l. 



PANEL_LABEL_STRING, 

"Label:", 



PANELJFONT, 

font_2. 



PANEL VALUE, 

"initial value". 



0); 



V. 



j 


The above call will cause both the label and the value for text_item to be ren¬ 
dered in font 2. 


4.9. File Descriptor Usage In SunView, each window is actually a device, /dev/win nnn, that is accessed 

through a file descriptor. Other packages such as the selection service also use 
file descriptors. In SunOS there is a limit to the number of file descriptors one 
program can have open; in Release 4.0 it is 64. Thus it is possible for your appli¬ 
cation to run out of file descriptors. 

The following table summarizes how file descriptors are used in SunView. 

Table 4-3 SunView File Descriptor Usage 


Window Type / 
Package 

FD Usage 

How FDs are used 

FRAME 

1 

1 for the window. 

CANVAS 

1 

1 for the window. 

TEXTSW 

3 

1 for the window, 

+ 1 for the file to be edited (if any), 

+ 1 for scratch (the /tmp/Text... file). 


(2) 

2 temporarily created during a save. 

PANEL 

1 

1 for the window. 

TTYSW 

2 

1 for the window, 

+ 1 for the pty (pseudo-tty). 

MENU 

0 

Fullscreen access uses the window’s FD. 

ALERT 

1 

1 for positioning 

Alerts have a frame and a panel; 
however, the FDs are allocated for the 
first alert and reused by subsequent alerts. 

Pointer 

0 

Most pointers are managed by the kernel. 

Icon 

0 

Frame uses same FD whether open or iconic. 
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Table 4-3 SunView File Descriptor Usage — Continued 


Window Type! 
Package 

FD Usage 

How FDs are used 

Scrollbar 

0 

(implemented as a region — read the 

SunView System Programmer’s Guide ) 

window manager 

(1) 

1 temporarily used for window 
management operations. 

UNIX 

3 

stdin/stdout/stderr 

4 

framebuffer 

1 

frame buffer FD gets allocated 
automatically with the base frame. The screen 
device must be opened for your program 
to draw on it. 

Selection Service 

3 

selection service fd’s 
are allocated whenever there is something 
that will set or get from the selection 
service. For example, if you put in 
selection service code or the first time 
a panel item is allocated. 


(1) 

This uses sockets to communicate: 

1 for the connection to the service 
+ 1 to receive UDP requests 
+ 1 TCP rendezvous socket for transfers. 

1 transiently opened when a transfer 
is in progress to carry it. 
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Canvases 


The most basic type of subwindow provided by SunView is the Canvas. A can¬ 
vas is essentially a window into which you can draw. 

For a demonstration of the various canvas attributes, run the program 
/usr/demo/canvas_demo. For examples of canvases that illustrate event 
handling, run the image editor iconedit(l). iconedit uses two canvases, 
the large drawing canvas on the left, and the small proof area on the lower right. 

In order to use canvases you must include the header file 
<suntool/canvas.h>. 

To give you a feeling for what you can do with canvases, the following page lists 
the available canvas attributes, functions and macros. Many of these are dis¬ 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the canvas summary tables in Chapter 
19, SunView Interface Summary : 

□ the Canvas Attributes table begins on page 319; 

□ the Canvas Functions and Macros table begins on page 320. 
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Canvas Attributes 

CANVAS_AUTO_CLEAR 

CANVAS_AUTO_EXPAND 

CANVAS_AUTO_SHRINK 

CANVAS_FAST_MONO 

CANVAS_FIXED_IMAGE 
CANVAS_HEIGHT 

CANVAS_MARGIN 

CANVAS__P IXWIN 

C ANVA S_REP AI NT_PROC 

CANVA S_RE SI ZE_PROC 
CANVAS_RETAINED 

CANVAS_WIDTH 


Canvas Functions and Macros 

canvas_event(canvas, event) 

canvas_ 

_window_event(canvas, event) 

canvas pixwin(canvas) 
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5.1. Creating and Drawing Like all windows in SunView, canvas subwindows are created with 

into a Canvas window_create (). When drawing into a canvas use the canvaspixwin, 

which you can get with the canvas_pixwin () macro. 

The pixwin is the structure through which you render images in a window. You 
draw points, lines and text on a pixwin with a set of functions of the form 
pw _*Jl ) — pw_write (), pw_vector (), pw_text () etc. 22 


Example 1: 


As a beginning example, the following program puts up a canvas containing a 
box with the words “Hello World!”: 


♦include <suntool/sunview.h> 

♦include <suntool/canvas.h> 

main(argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 

Canvas canvas; 

Pixwin *pw; 

/* create frame and canvas */ 

frame = window__create (NULL f FRAME, 0) ; 

canvas = windowhereate(frame, CANVAS, 0); 

/* get the canvas pixwin to draw into */ 
pw = canvas_pixwin(canvas); 

/* draw top, bottom, left, right borders of box */ 


pw_vector(pw. 

100, 

100, 

200, 

100, 

PIX_ 

SRC, 

»—i 

pw_vector(pw. 

100, 

200, 

200, 

200, 

PIX~ 

[SRC, 

l); 

pw__vector (pw. 

100, 

100, 

100, 

200, 

PIX_ 

SRC, 

l); 

pw_vector(pw. 

200, 

100, 

200, 

200, 

PIX_ 

SRC, 

l); 


/* write text at (125,150) in default font */ 
pw_text(pw, 125, 150, PIX_SRC, 0, "Hello World!"); 

window_main_loop(frame); 
exit(0); 


The PIX_SRC argument to pw_vector () and pw_text () is a rasterop 
function specifying the operation which is to produce the destination pixel 
values. There are several other rasterop functions besides P IX_SRC; they are 
described in Chapter 2 of the Pixrect Reference Manual. » 


22 Pixwins and their associated functions are covered in detail in Chapter 7, Imaging Facilities: Pixwins. 
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5.2. Scrolling Canvases 


Example 2: 


Many applications need to view and manipulate a large object through a smaller 
viewing window. To facilitate this SunView provides scrollbars, which can be 
attached to subwindows of type canvas, text or panel. 


The code below creates a canvas that is scrollable in both directions: 


frame = window_create(NULL, FRAME, 0) 
canvas = window_create(frame, CANVAS, 
CANVA S__AUT 0_SHR INK, 
CANVAS_WIDTH, 

CANVAS__HE IGHT, 

WIN_VERTICAL_SCROLLBAR, 

WIN_HORIZONTAL_SCROLLBAR, 
0 ); 


FALSE, 

1000 , 

1000 , 

scrollbar_create(0), 
scrollbar create(0), 


The distinction between the dimensions of the canvas and of the window is 
important In the above example, we set the canvas width and height to 1000 
pixels. Since the dimensions of the canvas subwindow (i.e. WIN_WIDTH and 
WIN_HEIGHT) were not explicitly set, the subwindow extends to fill the frame. 
The frame’s dimensions, in turn, were not explicitly set, so it defaults to 25 lines 
by 80 characters in the default font The result is a logical canvas roughly the 
area of the screen, which is viewed through a window about one fourth that size. 

NOTE It is necessary to explicitly disable the ‘‘auto-shrink” feature in the above exam¬ 
ple. If this were not done, the canvas size would be truncated to the size of the 
window. See Section 5.6, Automatic Sizing of the Canvas. 
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5.3. Canvas Model The components of a canvas subwindow and their relationships can be seen in 

Figure 5-1. 

Figure 5-1 Canvas Geometry 


Scrollbars 


WINDOW HEIGHT 



CANVAS WDTH 


(CAN VAS_WI DTH -1. 
CANVAS_HEIGHT-1) 


The Canvas Think of the canvas itself as a logical surface on which you can draw. The width 

and height of the canvas are set via the attributes CANVAS_WIDTH and 
CANVAS_HEIGHT. So the coordinate system is as shown in Figure 5-1, with the 
origin at the upper left comer and the point (CANVAS_WIDTH-1, 
CANVAS_HEIGHT-1) at the lower right comer. Note that the logical canvas 
origin is always at (0,0). 

The Canvas Pixwin As mentioned above, you draw on the canvas by writing into the canvas pixwin, 

which is retrieved via the CANVAS_PIXWIN attribute or the 
canvas_pixwin () macro. 

The canvas pixwin is set up to take scrolling into account by performing the 
transformation from your canvas coordinate system to its pixwin coordinate sys¬ 
tem. So when you draw into the canvas pixwin using the pw_* functions you 
don’t have to do any mapping yourself — the arguments you give should be in 
the canvas coordinate system. 

Between the frame border and the canvas pixwin is a margin, set via the attribute 
CANVAS_MARGIN. This margin defaults to zero pixels, so in the simple case, 
the canvas pixwin occupies the entire inner area of the window pixwin. If one or 
more scrollbars are present, the canvas margin begins at the inside border of the 
scrollbar. 

Note the distinction between the pixwin of the canvas (attribute 
CANVAS_P IXWIN) and the pixwin of the window (attribute WIN_PIXWIN). 

The canvas pixwin is one of several regions of the window’s pixwin, which also 
includes the regions occupied by the scrollbars and the margin. 

Revision A, of May 9, 1988 





















66 SunView 1 Programmer’s Guide 


5.4. Repainting 


Retained Canvases 


Non-Retained Canvases 


The Repaint Procedure 


The canvas package manages the canvas pixwin for you. In particular, the clip¬ 
ping list is restricted to the area of the canvas pixwin actually backed by the can¬ 
vas. This means that you can never draw off die edge of the canvas. For exam¬ 
ple, if you have set the canvas height to be less than the height of the canvas 
pixwin, any pw_* operations that attempt to draw below the canvas height will 
be clipped away. 

By default, canvases are retained — i.e. the canvas package maintains a copy of 
the bits on the screen in a backing pixrect, from which it automatically repaints 
the screen image when necessary. If you wish to handle repainting yourself, you 
can defeat this feature. 

The canvas package allocates a backing pixrect the size of the logical canvas. 
When the canvas width or height changes, a new backing pixrect of the proper 
dimensions is allocated, the contents of the old pixrect are copied into the new 
pixrect, and the old pixrect is freed. 

For a non-retained canvas, set CANVAS_RETAINED to FALSE, and give your 
own repaint function as the value of CANVAS_REPAlNT_PROC. 

The repaint procedure is called whenever some part of the canvas has to be 
repainted onto the canvas pixwia Note that if you supply a repaint proc, it will 
be called even if the canvas is retained — i.e. the canvas package will not 
automatically copy from the backing pixrect to the canvas pixwin. 

The form of the repaint procedure is: 

sample_repaint_proc(canvas, pixwin, repaint_area) 

Canvas canvas; 

Pixwin *pixwin; 

Rectlist *repaint_area; 

The first two arguments are the canvas and its pixwin (i.e. the value of 
canvas_pixwin (canvas)). The third argument, repaint_area, is a 
pointer to a list of rectangles (type Rectlist *) which define the area to be 
painted. 23 

Before the canvas package calls your repaint procedure, it restricts the clipping 
list to the area which needs to be painted. Thus if your application is not capable 
of repainting arbitrary areas of the canvas you can repaint the entire image 
without worrying about excessive repainting. 

If you choose not to redraw each individual rect in the repaint area, you can use 
the rectangle given by repaint_area->rl_bound, which is the bounding 
rectangle for the repaint area. 

Note that if the attribute CANVAS_AUTO_CLEAR is TRUE, the canvas package 
will clear the repaint area before calling your repaint procedure. 


23 Rectlists are covered in detail in the chapter on Reds and Redlists in the SunView 1 System 
Programmer’s Guide. 
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A retained canvas has two advantages. First, the repainting will be faster since it 
is a simple block copy operation. Second, it eliminates the need for the applica¬ 
tion to keep a display list from which to regenerate the image. 

On the other hand there is a performance penalty on writing, since each operation 
is performed both on the canvas pixwin and the backing pixrect. This penalty 
may be reduced by using the pw_bat ch () call described in the chapter entitled 
Imaging Facilities: Pixwins. 

The client’s resize procedure is called whenever the canvas width or height 
changes. Its form is: 

sample_resize_proc(canvas, width, height) 

Canvas canvas; 

int width; 

int height; 

NOTE You should never repaint the image in the resize procedure, since if there is any 
new area to be painted, the repaint procedure will be called later. 

There are some subtle points to be aware of related to whether or not the image is 
fixed size (CANVAS_FIXED_IMAGE is TRUE). In the default case the image is 
fixed size, and the repaint procedure will not be called when the canvas gets 
smaller, since there will be no new canvas area to be repainted. If the image is 
not fixed size, then whenever the canvas size changes, the canvas package 
assumes that the entire canvas needs to be repainted, and the repaint area will 
contain the entire canvas. 

Initializing a Canvas Neither the repaint procedure nor the resize procedure will be called until the 

canvas subwindow has been displayed at least once. This allows you to create 
and initialize a canvas without having to deal with the resize/repaint procedures. 
The very first time the canvas is displayed, the resize procedure will be called 
with the current canvas size. This initial call to the resize procedure allows you 
to synchronize with the canvas size. 


Retained vs. Non-Retained 


5.5. Tracking Changes in 
the Canvas Size 
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Example 3: 


The canvas in the program below has a repaint procedure which fills the canvas 
with an appropriately sized rectangle and diagonals. 


♦include <suntool/sunview.h> 
♦include <suntool/canvas,h> 

static void repaint_canvas(); 

main(argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 


frame = window_create(NULL, FRAME, 0); 
window_create(frame, CANVAS, 

CANVAS__RET AI NED, FALSE, 

CANVAS_FIXED_IMAGE, FALSE, 

CANVAS_REP AI NT_PROC, repa int_canva s, 

0 ); 

window_main_loop (frame); 
exit(0); 


static void 

repaint_canvas(canvas, pw, repaint_area) 


Canvas 

canvas; 

Pixwin * 

pw; 

Rectlist * 

repaint_area; 

int width 

= (int)window_get(canvas 

int height 

= (int)window get(canvas 

int margin 

= 10; 

int xleft 

= margin; 

int xright 

= width - margin; 

int ytop 

= margin; 

int ybottom 

= height - margin; 


CANVAS_WIDTH); 
CANVAS_HEIGHT) ; 


/* draw box */ k 

pw_vector(pw, xleft, ytop, xright, ytop, PIX_SRC, 1); 
pw__vector (pw, xright, ytop, xright, ybottom, PIX_SRC, 1); 
pw_vector(pw, xright, ybottom, xleft, ybottom, PIX_SRC, 1); 
pw_vector(pw, xleft, ybottom, xleft, ytop, PIX_SRC, 1); 

/* draw diagonals */ 

pw_vector(pw, xleft, ytop, xright, ybottom, PIX_SRC, 1); 
pw_vector(pw, xright, ytop, xleft, ybottom, PIX_SRC, 1); 


#sun 

Xr microsystems 


Revision A, of May 9, 1988 








Chapter 5 — Canvases 69 


There are several points to note from the example on the previous page. First, 
since the width and height of the canvas are not specified, they default to the 
width and height of the window. Second, since the image being drawn is depen¬ 
dent on the size of the canvas, we set CANVAS_FIXED_IMAGE to FALSE. 
Third, when the repaint proc is called, we don’t bother to draw the specified 
repaint area, instead we rely on the clipping list to be restricted correctly and 
simply redraw the entire image. 

5.6. Automatic Sizing of Two attributes requiring some explanation are CANVAS_AUTO_EXPAND and 
the Canvas CANVAS_AUTO_SHRiNK. Setting both these attributes to true allows you to 

have a drawing area which automatically tracks the size of the window. 

If CANVAS_AUTO_EXPAND is TRUE, the canvas width and height are never 
allowed to be less than the edges of the canvas pixwin. For example, if you try to 
set CANVAS_WIDTH to a value which is smaller than the width of the canvas 
pixwin, the value will be automatically expanded (rounded up) to the width of 
the canvas pixwin. 

The main use of CANVAS_AUTO_EXPAND is to allow the canvas to grow bigger 
as the user stretches the window. For example, if the canvas starts out exactly 
the same size as the canvas pixwin, and the user stretches the window, the canvas 
pixwin will get bigger, which will cause the canvas itself to expand. 

Another point to keep in mind is that whenever you set 

CANVAS_AUT0_EXPAND to TRUE, the canvas will be expanded to the edges of 
the canvas pixwin (if it is smaller to begin with). 

CANVAS_AUTO_SHRINK is symmetrical to CANVAS_AUTO_EXPAND. If 
CANVAS_AUTO_SHRINK is TRUE, the canvas width and height are never 
allowed to be greater than the edges of the canvas pixwin. 

NOTE As described in Section 4.8, Attribute Ordering, the canvas attributes are 

evaluated before the generic window attributes. This means that, if you want to 
set the window size and then disable automatic sizing of the canvas, you must 
first set the window size, then, in a separate window_set () call, disable 
CANVAS_AUTO_S HRINK and/or CANVAS_AUTO_EXPAND. If you do both in 
the same call, the auto-sizing will be turned off before the window size is set, so 
the canvas size will not match the window size you specify. Here is an example 
of how to do it correctly: 

r - - --—--\ 

canvas = window_create(frame, CANVAS, 

WIN_HEIGHT, 400, 

WIN_WIDTH, 600, 

0 ); 

window_set(canvas, 

CANVAS_AUTO_SHRINK, FALSE, 

CANVAS_AUTO_EXPAND, FALSE, 

0 ); 

^ 
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5.7. Handling Input in This section gives some hints on basic handling of input in canvases. 24 

Canvases 

Default Input Mask By default, canvases enable LOC_WlNENTER, LOC_wiNEXIT, LOC_MOVE and 

the three mouse buttons, MS__LEFT, MS_MIDDLE and MS_RIGHT. 2 - 5 

NOTE Since the canvas pixwin is actually a region of the subwindow’s pixwin, your 

event procedure will receive LOC_RGNENTER and LOC_RGNEXIT events 
rather than LOC_WINENTER and L0C_WINEXIT. The locator motion events 
— LOC_MOVE, LOC_STILL, LOC_DRAG, and LOC_TRAJECTORY —will 
only be passed to your event procedure if they fall within the canvas pixwia 

You can enable events other than those listed above with the window attributes 
applying to events. So, for example, you could allow the user to type in text to a 
canvas by calling: 

---- 

window_set(canvas, WIN_CONSUME_KBD_EVENT, WIN_ASCII_EVENTS, 0); 

s___/ 


An application needing to track mouse motion with the button down would 
enable LOC_DRAG by calling: 

- —— - > 

window_set(canvas, WIN_CONSUME_PICK_EVENT, LOC_DRAG, 0); 

« __ _/ 


Writing Your Own Event 
Procedure 


Translating Events from 
Canvas to Window Space 


If you supply an event procedure as the value of WIN_event_PROC, it will get 
called when any event is received for the canvas. Before your event procedure 
gets called, however, the canvas package does some processing. If the event is 
WIN_REPAINT or WIN_RESIZE, the canvas package calls your repaint or 
resize procedures if necessary. If the event is SCROLL_REQUEST, then the can¬ 
vas package performs the scroll. 26 The repaint, resize and scroll events are then 
passed to your event procedure. In the case of events which have x-y coordi¬ 
nates, the canvas package translates the events from the coordinate space of the 
canvas pixwin to that of the logical canvas. 

Functions are provided to translate event coordinates from the coordinate space 
of the canvas to the coordinate space of the canvas subwindow, and vice versa. 

To go from canvas space to window space, use canvas_window_event (). 
Keep in mind that the canvas_window_event function changes fields in its 
event argument structure. For example, if you want to put up a menu in a canvas 

24 The general input paradigm for Sunview is discussed in Chapter 6, Handling Input. See that chapter for a 
full discussion of the available input events and how to use them. 

25 Note that the canvas package expects to receive these events, and will not function properly if you disable 
them. Also, if the user has the enabled the LeftJIanded option in the Input category of default sedit(l), 
the mouse buttons are reversed: MS LEFT refers to the right mouse button, MS_RIGHT to the left mouse 
button. 

26 If you want write a procedure which is called before the repaint, resize or scroll event is processed by the 
canvas package, in order to modify the interpretation of the event, you must interpose on the event, as described 
in Chapter 17, The Notifier . 
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subwindow, you need to specify the menu’s location in the coordinate of the 
subwindow, not of the canvas. 

To go from window space to canvas space, use canvas_event (). This 
returns the Event * it is passed, with the x and y fields changed. The transla¬ 
tion is necessary if you read your own events with window_read_event () , 
described in the next chapter, Handling Input. 

Border Highlighting 

The SunView convention is that a subwindow indicates that it is accepting key¬ 
board events by highlighted its border. By default, canvas subwindows do not 
enable any keyboard events, so the border is not highlighted. However, if you 
explicitly enable keyboard events, by consuming WIN_ASCII_EVENTS, the 
canvas package will highlight the canvas border when it is given the input focus. 

Example 4: 

The program below prints out the corresponding string when the user types 0,1, 
or 2 into its canvas: 

r i 

#include <suntool/sunview.h> 

#include <suntool/canvas.h> 

static void my_event_j?roc () ; 

main(argc, argv) 
int argc; 

char **argv; 

{ 

Frame frame; 

frame = window create(NULL, FRAME, 0); 
window_create(frame, CANVAS, 

WIN_CONSUME_KBD__E VENT, WIN_ASCI I_EVENTS , 

WIN EVENT PROC, my event_j?roc, 

0) ; 

window_main_loop (frame) ; 
exit(0) ; 

} 

static void 

my_event_j?roc (canvas, event) 

Canvas canvas; 

Event *event; 

{ 

char *string = NULL; 

switch ( event_action(event) ) { 

case ' 0' : 

string = "zero”; 
break; 

case '1': 

string = "one "; 
break; 

i .- -J 
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r 


case ' 2' : 

string = "two 
break; 


default: 
break; 


if (string != NULL) 

pw_text(canvas^pixwin(canvas), 

10, 10, PIX_SRC, NULL, string); 




5.8. Color in Canvases 

Setting the Colormap Segment 

Color in Retained Canvases 

Color in Scrollable Canvases 


You can use color in canvases by specifying a colormap segment for the canvas 
with the colormap manipulation routines described in Chapter 6, Handling Input. 

The first thing to note is that since the canvas pixwin is a region of the 
WIN_P IXWIN, you must also set the colormap segment for the canvas pixwin. 

If the canvas is retained, then the colormap segment must be set before 
CANVAS_RETAINED is set to TRUE. This is because the canvas package will 
determine the depth of the backing pixrect based on depth of the colormap seg¬ 
ment defined for the WIN_P IXWIN. (If the colormap segment depth is greater 
than two, then the full depth of the display will be used. Otherwise, the backing 
pixrect depth will be set to one.) 

Since the depth of the backing pixrect is determined when the canvas is created, 
you must create the canvas with CANVAS_RETAINED false, then set the 
colormap segment, then set CANVAS_RETAINED to TRUE. 

If the canvas has scrollbars, you need to attach the scrollbars to the canvas after 
the colormap segment has been changed. If the canvas has already been created 
with scrollbars attached, you should change the colormap, then re-attach the 
scrollbars. This will insure that the scrollbar pixwin regions use the new color- 
map segment. 


5.8. Color in Canvases 

Setting the Colormap Segment 

Color in Retained Canvases 

Color in Scrollable Canvases 
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Example 5: 


Below is an example of setting the colormap segment for a canvas: 
r -—-- 

♦include <suntool/sunview,h> 

♦include <suntool/canvas.h> 

♦include <sunwindow/cms rainbow.h> 


init__color_canvas (base__f rame) 

Frame basenframe; 

{ 

{ 

Canvas canvas; 

Pixwin *pw; 

unsigned char red[CMS_RAINBOWSIZE]; 
unsigned char green[CMS_RAINBOWSIZE]; 
unsigned char blue[CMS_RAINBOWSIZE]; 

canvas = window_create (base__f rame, CANVAS, 

CANVAS_RETAINED f FALSE, 

0 ); 

cms_rainbowsetup(red, green, blue); 

/* set the WIN_PIXWIN colormap */ 

pw = (Pixwin *) window_get(canvas, WIN_PIXWIN); 

pw_setcmsname(pw, CMS_RAINBOW); 

pw_putcolormap(pw, 0, CMS_RAINBOWSIZE, red, green, blue); 

/* set the CANVAS_PIXWIN colormap */ 
pw = (Pixwin *) canvas_pixwin(canvas); 
pw_s et cmsname(pw, CMS_RAINBOW); 

pw_j>utcolormap(pw, 0, CMS_RAINBOWSIZE, red, green, blue); 

window_set(canvas, 

CANVAS_RETAINED, TRUE, 

WIN__VERTICAL_SCROLLBAR, scrollbar__create (0) , 

WIN_H0RIZONTAL_SCROLLBAR, scrollbar_create(0), 

0 ); 

} 

} 

V_ 
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Summary Listing and Tables 



This chapter explains how input is handled in SunView. Specifically it: 
o gives an overview on how input is handled in SunView 

□ describes events and how they are used; 

□ gives various classes of events — Ascn, action events, function keys, locator 
buttons, locator motion, window generated events, and so on; 

□ explains the input focus model distinguishing between pick and keyboard 
focuses; 

□ shows how to control where input is distributed using input masks', 

□ shows how to query the state of an event; 

□ shows how to explicitly read events. 

The material in this chapter applies to the window system as a whole. However, 
it is of special interest to alerts or clients of canvases, who typically will want to 
handle events themselves. 

The definitions necessary to use SunView’s input facilities are in the header file 
<sunwindow/win_input. h>, which is included by 
<sunwindow/window_hs. h>, which in turn is included by default when 
you include <suntool/sunview.h>. 

The chapter titled Workstations in the SunView 1 System Programmer’s Guide 
explains the input system at a lower level, covering such topics as how to add 
user input devices to SunView. 

To give you a feeling for what you can do with events, a list of the available 
event descriptors and input related window events is given on the following page. 
Many of these are discussed in the rest of this chapter and elsewhere (use the 
Index to check). All are briefly described with their arguments in the input sum¬ 
mary tables in Chapter 19, SunView Interface Summary : 

□ the Event Descriptors table begins on page 333; 

□ the Input-Related Window Attributes table begins on page 334. 
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Input-Related Window Attributes 

WIN_INPUT_DESIGNEE 

WIN_CONSUME_KBD_EVENTS 

WIN_GRAB_ALL_INPUT 

WIN_IGNORE_KBD_EVENTS 

WIN_KBD_FOCUS 

WIN_CONSUME_PICK_EVENT 

WIN_KBD_INPUT_MAS K 

WIN_IGNORE_PICK_EVENT 

WINJPICK_INPUT_MASK 

WIN_CONSUME_PICK_EVENTS 

WIN_CONSUME_KBD_EVENT 

WIN_IGNORE_PICK_EVENTS 

WIN_IGNORE_KBD_EVENT 



Event Descriptors 

WIN_NO_EVENTS 


WIN_RIGHT_KEYS 

WIN_ASCII_E VENTS 


WIN_TOP_KEYS 

WIN_IN_TRANSIT_EVENTS 


WIN_UP_ASCII_EVENTS 

WIN_LEFT_KEYS 


WIN_UP_EVENTS 

WIN_MOUS E_BUTTONS 




msun 

XT microsystems 


Revision A, of May 9, 1988 












Chapter 6 — Handling Input 79 


6.1. An Overview of the The input environment for SunView differs from UNIX programs. Most UNIX 

Input Environment programs read characters from standard input by using either the read(2) system 

call or the standard I/O functions such as getc(3S), gets(3S), or scanf(3S). 
SunView is different in that the underlying Notifier formats user input into uni¬ 
form events, which it distributes to the window’s event procedure. 

How are events generated ? Figure 6-1 illustrates how events are generated and handled in SunView. 

Figure 6-1 Input Events 
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What does the Notifier do with 
these events ? 

Events are generated from several sources. These include standard devices such 
as the keyboard and mouse, special input devices such as graphics tablets, and 
the window system itself. 

SunView does not directly receive events from the hardware devices. Instead 
each user action is interpreted by a “virtual” user input device (VUID) interface. 
This interface packages the data it receives into an event and sends it to the appli¬ 
cation process. 27 

The Notifier weaves events from all of these sources into a single, ordered event 
stream. This event stream eliminates the need for the application to poll separate 
streams from the different devices. 

Because the underlying Notifier multiplexes the input stream between windows, 
each individual window operates under the illusion that it has the user’s full 
attention. That is, it sees precisely those input events that the user has directed to 
it. 

How do windows determine 
which input they will receive? 

Each window indicates which events it is prepared to handle using input masks , 
described in Section 6.6, Controlling Input in a Window. These masks only let 
specified events through to the process. 

6.2. Events 

As discussed in the previous section, each user action generates an input event. 
This event is passed to your event procedure as an Event pointer (type 

Event *). Three types of information are encoded as part of an event: 

□ an identifying code, accessed with the macro event_act ion () 

□ the location of the event in the window’s coordinate system, accessed with 
the macros event_x () and event_y () 

□ a timestamp, accessed with the macro event_time () 

Notice that the macro event_action () has replaced the old event_id (). 
For compatibility reasons, event_id () is still supported, so that old code that 
does not use the new action event codes will still work. See Section 6.4, Classes 
of Events, for an explanation of action events. New programs that want to take 
advantage of the new action events must use the event_act ion () macro. 

An event Procedure 

Use the following form to specify an an event procedure in your applications: 

void 

sample event_proc(window, event, arg) 

Window window; 

Event *event; 

caddr_t arg; 


27 It is possible to bypass the VUID and receive unencoded events. Refer to the section on Unencoded Input 
in Chapter 7 of the SunView 1 System Programmer s Guide. 
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How Subwindows Handle 
Events 


6.3. A List of Events 


The arguments passed in are the window, the event, and an optional argument 
containing data pertaining to the event. For example, if the event is a 
SCROLL_REQUEST, arg will be the scrollbar that sent the event. 

The canvas and panel subwindows pass events that they receive on to an event 
procedure. These event procedures are supplied by the application as the value 
of WlN_EVENT_PROC. If you set the WlN_EVENT_PROC of a canvas or panel 
to a function you have written, you can receive events after they have been pro¬ 
cessed by the canvas or panel. Both the canvas and panel packages process 
SCROLL_REQUEST, WIN_RESIZE, and WIN_REPAINT events before calling 
your event procedure. The form of an event procedure is: 

void 

sample__event_proc (window , event, arg) 

Window window; 

Event event; 

caddr__t arg; 

The arguments passed in are the window (canvas or panel), the event, and an 
optional argument containing data pertaining to the event. For example, if the 
event is a SCROLL_REQUEST, arg will be the scrollbar that sent the event. 

The default panel event procedure maps events to actions and determines which 
panel item to send the event to. The default canvas event procedure does no 
further processing of the event. You can call the default window event procedure 
by calling window_def ault event_proc () with the same arguments 
passed to your event procedure.^ 

Two tables are given on the following pages. Table 6-1, Event Codes, lists the 
predefined event codes and their values. 29 The event id or code numbers that the 
window system uses to represent an event are included in this table. These event 
code numbers are in the range of 0-65535. The numbers are useful when debug¬ 
ging a program because the debugger reports event codes as decimal integers and 
not as names. 

Table 6-2, Keyboard Motions and Accelerators, lists the event name and its asso¬ 
ciated keyboard accelerator. 


28 If you need to receive an event before it is processed by a canvas, panel, or any other type of window, you 
can use the more general notifier interposition mechanism described in Chapter 17, The Notifier , 

29 The same table also appears in the input summary section of Chapter 19, SunView Interface Summary. 
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Table 6-1 Event Codes 


Event Code 

Description 

Value (for debugging) 

ASCII FIRST 

Marks beginning of ASCII range 

0 

ASCII LAST 

Marks end of ASCII range 

127 

META FIRST 

Marks beginning of META range 

128 

META_LAST 

Marks end of META range 

255 

ACTION ERASE CHAR BACKWARD 

Erase char to the left of caret 

31744 

ACTION ERASE CHAR FORWARD 

Erase char to the right of caret 

31745 

ACTION ERASE WORD BACKWARD 

Erase word to the left of caret 

31746 

ACTION ERASE WORD FORWARD 

Erase word to the right of caret 

31747 

ACTION ERASE LINE BACKWARD 

Erase to the beginning of the line 

31748 

ACTION_ERASE_LINE_END 

Erase to the end of the line 

31749 

ACTION GO CHAR BACKWARD 

Move the caret one character to the left 

31752 

ACTION GO CHAR FORWARD 

Move the caret one character to the right 

31753 

ACTION GO WORD BACKWARD 

Move the caret one word to the left 

31754 

ACTION GO WORD END 

Move the caret to the end of the word 

31756 

ACTION GO WORD FORWARD 

Move the caret one word to the right 

31755 

ACTION GO LINE BACKWARD 

Move the caret to the start of the line 

31757 

ACTION_GO_LINE_END 

Move the caret to the end of the line 

31759 

ACTION_GO_LINE_FORWARD 

Move the caret to the start of the next line 

31758 

ACTION_GO_COLUMN_BACKWARD 

Move the caret up one line, 
maintaining column position 

31761 

ACTION_GO_COLUMN_FORWARD 

Move the caret down one line, 
maintaining column position 

31762 

ACTION_GO_DOCUMENT_START 

Move the caret to the beginning of the text 

31763 

ACTION_GO_DOCUMENT_END 

Move the caret to the end of the text 

31764 

ACTION_STOP 

Stop the operation 

31767 

ACTION_AGAIN 

Repeat previous operation 

31768 

ACT I ON_P ROP S 

Show property sheet window 

31769 

ACTION_UNDO 

Undo previous operation 

31770 

ACTION_FRONT 

Bring window to the front of the desktop 

31772 

ACTION_BACK 

Put the window at the back of the desktop 

31773 

ACTION_OPEN 

Open a window from its icon form or close 
if already open) 

31775 

ACTION_CLOSE 

Close a window to an icon 

31776 

ACTION_COPY 

Copy the selection to the clipboard 

31774 

ACTION_PASTE 

Copy clipboard contents to the insertion point 

31777 

ACTION_CUT 

Delete the selection, put on clipboard 

31781 

ACTION_COPY_THEN_PASTE 

Copies then pastes text 

31784 

ACTION_FIND_FORWARD 

Find the text selection to the right of the caret 

31779 

ACTION_FIND_BACKWARD 

Find the text selection to the left of the caret 

31778 

ACTION_FIND_AND_REPLACE 

Show find and replace window 

31780 

ACTION SELECT_FIELD_FORWARD 

Select the next delimited field 

31783 

ACTION_SELECT_FIELD_BACKWARD 

Select the previous delimited field 

31782 
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Table 6-1 Event Codes — Continued 


Event Code 

Description 

Value (for debugging) 

ACT I ON_MATCHJDELI MI TER 

Selects text up to a matching delimiter 

31894 

ACT I ON__QUOTE 

Causes next event in the input stream to 
pass untranslated by the keymapping system 

31898 

ACT I ON_EMP T Y 

Causes the subwindow to be emptied 

31899 

ACTION_STORE 

Stores the specified selection as a new file 

31785 

ACT I ON__LOAD 

Loads the specified selection as a new file 

31786 

ACT I ON_GET_F ILENAME 

Gets the selected filename 

31788 

ACTION_SET_DIRECTORY 

Sets the directory to the selection 

31788 

ACTION_INCLUDE_FILE 

Selects the current line (in pending-delete mode) 
and attempts to insert the file described by that selection 

31891 

ACTION_CAP S_LOCK 

Toggle caps lock state 

31895 

PANEL_EVENT_CANCEL 

The panel or panel item is no longer “current” 

32000 

P ANEL_E VENT_MOVE__I N 

The panel or panel item was entered 
with no mouse buttons down 

32001 

PANEL_EVENT_DRAG_IN 

The panel or panel item was entered with one or more 
mouse buttons down 

32002 

SCROLL_REQUEST 

Scrolling has been requested 

32256 

SCROLL_ENTER 

Locator (mouse) has moved into the scrollbar 

32257 

SCROLL_EXIT 

Locator (mouse) has moved out of the scrollbar 

32258 

LOC_MOVE 

Locator (mouse) has moved 

32512 

LOC__STILL 

Locator (mouse) has been still for 1/5 second 

32513 

LOC_WI NENTER 

Locator (mouse) has entered window 

32514 

LOC_WINEXIT 

Locator (mouse) has exited window 

32515 

LOC_DRAG 

Locator (mouse) has moved while a button was down 

32516 

LOC_RGNENTER 

Locator (mouse) has entered a region of the window 

32519 

LOC_RGNEXIT 

Locator (mouse) has exited a region of the window 

32520 

LOCJTRAJECTORY 

Inhibits the collapse of mouse motions; clients receive 
LOC_TRA JECTORY events for every locator motion 
the window system detects. 

32523 

WIN_REPAINT 

Some portion of window requires repainting 

32517 

WIN_RESIZE 

Window has been resized 

32518 

WIN_STOP 

User has pressed the stop key 

32522 

KBD_REQUEST 

Window is about to become the focus of keyboard input 

32526 

KBD_USE 

Window is now the focus of keyboard input 

32524 

KBD_DONE 

Window is no longer the focus of keyboard input 

32525 

SHIFT_LEFT 

Left shift key changed state 

32530 

SHIFT_RIGHT 

Right shift key changed state 

32531 

SHIFT__CTRL 

Control key changed state 

32532 

SHIFT_META 

Meta key changed state 

32534 

SHIFT_LOCK 

Shift lock key changed state 

32529 

SHIFT_CAPSLOCK 

Caps lock key changed state 

32528 
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Table 6-1 

Event Codes — Continued 


Event Code 

Description 

Value (for debugging) 

BUT (i) 

MS_LEFT 

MS_MIDDLE 

MS_RIGHT 


Locator (mouse) buttons 1-10 

Left mouse button 

Middle mouse button 

Right mouse button 

BUT(l) is 32544 

32544 

32545 

32546 

KEY_LEFT(i) 
KEY_RIGHT(i) 
KEYJTOP(i) 


Left function keys 1-15 

Right function keys 1-15 

Top function keys 1-15 

KEY_LEFT (1) is 32554 
KEY_RIGHT (1) is 32570 
KEYJTOP (1) is 32586 
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Table 6-2 Keyboard Motions and Accelerators 


Command Token 

SunView 4.0 

SunView 3.x 

ACTION_ERASE_CHAR_BACKWARD 

f Delete 1 

(Delete ] 

ACTION_ERASE_CHAR_FORWARD 

1 Shift-Delete 1 

l Shift-Delete 1 

ACT I ON_ERAS E_W ORD_B ACKWARD 

iControl-Wl 

l£snwvJ-wj 

ACTION_ERASE_WORD_FORWARD 

IShift-Control-W J 

l Shift-Control-W I 

ACTION_ERASE_LINE_BACKWARD 

(Control-U 1 

l Control-U 1 

ACTION_ERASE_LINE_END 

1 Shift-Control-U 1 

1 Shift-Control-U 1 

ACTION_GO_CHAR_BACKWARD 

l Control-B 1 or ( Shift-Control-F 1 or 

fRlol 


ACTION_GO_CHAR_FORWARD 

[ Control-F 1 or I Shift-Control-B 1 or 

fRin 


ACTION_GO_WORD_BACKWARD 

(Control -comma 1 or 

I Sbifl-ConlTol-Deriod ) or 
[ Shift-Control-s/ayA) 


ACT I ON__GO_WORD_END 

l Control -period 1 


ACTION_GO_WORD_FORWARD 

(Control-s/as/t) or 
[ Shift-Control-cewvra 1 


ACTION_GO_LINE_FORWARD 

l Control-semicolon ) or f Rll 1 


ACTION_GO_LINE_BACKWARD 

I Control-A 1 or l Shift-Control-E 1 


ACT I ON_GO_LI NE_END 

l Control-JEJ or [ Shift-Control-A) 


ACT I ON_GO_COLUMN_BACKWARD 

LCQD.lrgl-.EJ or [ Shift-Control-N) or 

IrTTI 


ACTION_GO_COLUMN_FORWARD 

l Control-N J or 1 Shift-Control-P) or 

IrTFI 


ACTI ON_GO_DOCUMENT_START 

(Shift-Control-Retum ) or [ R7 ] 


ACTION__GO_DOCUMENT_END 

I Control-Return 1 or [ R13 1 

l Control-Return 1 

ACTI ON_ST OP 

fin 

rm 

ACTION_AGAIN 

[ L2l or 1 Meta-k 1 

rm 

ACT I ON__PROP S 

rm 

rm 

ACTION_UNDO 

im or 1 Meta-U 1 

rm 

ACTION_FRONT 

rm 

rm 

ACTION_BACK 

1 Shift-L5 1 

lShift-L5j 

ACTION_OPEN 

rm 

rm 

ACTION_CLOSE 

I Shift-L71 

[ Shift-L71 

ACT I ON__COP Y 

fL6) or 1 Meta-Cl 

rm 

ACTION_PASTE 

fin or 1 Meta-V 1 

ILL) or LCaniral-C J 

ACTION_CUT 

fOol orlMfW-X J 

I.LHL) or l Control-D 1 

ACT I ON_COP Y_THEN_P ASTE 

1 Meta-? ] 

(Control-P) 

ACT I ON_F I ND_FORWARD 

(m or I Meta-F1 

( L9 1 or 1 Control-F 1 

ACT I ON_F I ND_BACKWARD 

1 Shift-L9 1 or [ Shift-Meto-F 1 

l Shift-L9 lor l Shift-Control-F 1 

ACTION_FIND_AND_REPLACE 

1 Control-L9 1 


ACTION_SELECT_FIELD_FORWARD 

IConnai-TabJ 


ACTION_SELECT_FIELD_BACKWARD 

LShift-CQnirQl-Ia!? J 


ACT I ON__MATCH_DELI MI TER 

I Meta-D ) 


ACTION_QUOTE 

1 Meta-O ) 


ACTION_EMPTY (Document) 

l Mela- E 1 


ACT I ON__STORE 

1 Meto-S) 
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Table 6-2 Keyboard Motions and Accelerators — Continued 


Command Token 

SunView 4.0 

SunView 3.x 

ACTION_LOAD 

I Meta- LI 


ACTION_INCLUDE_FILE 

I Meta-l I 


ACTION_HELP 30 

l Meta-1 J (l Mefa-ShiftZ!) 


ACTION_GET_FILENAME 

[ Escape) 

l Escape. J 

ACTION_CAPS_LOCK 

rm 

rm 


6.4. Classes of Events 


ASCT Events 


Locator Button Events 


Locator Motion Events 


This section groups each of the events described in Table 6-1, Event Codes, into 
logical classes. Each class is described below. 

The event codes in the range 0 to 255 inclusive are assigned to the ASCII event 
class. This includes the standard 7-bit ASCII codes and their 8-bit META coun¬ 
terparts. 

If a user strikes a key which has an obvious ASCII meaning; that is, a key in the 
main typing array labeled with a single letter, it causes the VUID to enqueue for 
the appropriate window an event whose code is the corresponding 7-bit ASCII 
character. 

The META event code values (128 through 255) are generated when the user 
strikes a key that would generate a 7-bit ASCII code while the META key is also 
depressed. 

The standard Sim locator is a three button mouse, whose buttons generate the 
event codes MS_LEFT, MS_MIDDLE and MS_RIGHT. 

In general, a physical locator can have up to 10 buttons connected to it. In some 
cases, the locator itself may not have any buttons on it; however, it may have 
buttons from another device assigned to it. A light pen is an example of such a 
locator. 

Each button that is associated with the VUID’s locator is assigned an event code; 
the i-th button is assigned the code BUT ( i ). Thus the event codes MS_LEFT, 
MS_MIDDLE and MS_RIGHT correspond to BUT (1), BUT (2) and BUT (3). 

The physical locator constantly provides an (x, y) coordinate position in pixels; 
this position is transformed by SunView to the coordinate system of the window 
receiving an event. Locator motion event codes include LOC_MOVE, 
LOC_DRAG, LOC_TRAJECTORY, and LOC_STILL. 

Since the locator tracking mechanism reports the current position at a set sam¬ 
pling rate, 40 times per second, fast motions will yield non-adjacent locations in 
consecutive events. 


30 If your keyboard has the IL161 key, you may also use it. 
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Window Events 


Resize & Repaint Events 


A LOC_MOVE event is reported when the locator moves, regardless of the state 
of the locator buttons. If you only want to know about locator motion when a 
button is down, then enable LOC_DRAG instead of LOC_MOVE. This will 
greatly reduce the number of motion events that your application has to process. 

When you enable LOC_MOVE or LOC_DRAG, the window system gives you the 
current locator position by collapsing consecutive locator motion events into one. 
This operation is appropriate for applications such as dragging an image from 
one point to another, in which it is important to keep up with the mouse cursor. 

For some applications, however, each point on the cursor trajectory is of interest; 
for example, a program that lets the user draw. In these situations you may not 
want to collapse consecutive motion events. In such a situation you should ask 
for LOC_TRA JECTORY events, which suppresses any event collapsing so that 
you get all the locator movements that the window system sees. 

Note that when you ask for LOC_TRAJECTORY events, you get (many!) 
LOC_TRA JECTORY events in place of LOC_MOVE’s, but you still get 
LOC_drag events if you have enabled them. 

If you ask for LOC_STILL, a single L0C_STILL event will be reported after 
the locator has been still for 1/5 of a second. 


Window events are generated by the window system itself. They are meaningful 
only to the window to which they are directed. 

To be informed when the locator enters or exits a window, enable events with the 
codes LOC_WINENTER and LOC_WINEXIT. 

NOTE If you are using the tile mechanism described in the S unView 1 System 

Programmer’s Guide, then you will be told when the locator has entered or 
exited a tile using the LOC_RGNENTER and L0C_RGNEXIT events. To receive 
these events you must also have LOC_MOVE enabled. 

When the size of a window is changed (either by the user or programmatically) a 
WIN_RESIZE event is generated to give the client a chance to adjust any 
relevant internal state to the new window size. You should not repaint the screen 
on receiving a resize event. You will receive a separate WIN_REPAINT event 
when a portion of the window needs to be repainted. 

NOTE If you are using a canvas subwindow you will not need to track resize and 

repaint events directly. The canvas package receives these events, computes the 
new window dimensions or the precise area requiring repainting, and calls your 
resize or repaint procedures directly. See Chapter 5, Canvases for more details. 
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Keyboard Focus Events 


Stop Event 


Function Key Events 


Three events let your application interact with the keyboard focus mechanism 
(the keyboard focus is explained in section 6.6, Controlling Input in a Window ). 
When the user explicitly directs the keyboard focus towards your window, you 
will receive a KBD_REQUEST event. Your window will then become the key¬ 
board focus unless you call window_ref use_kbd_f ocus (). Refusing the 
keyboard focus, when you don’t need it, contributes to the usefulness of the split 
keyboard/pick focus mode available as a runtime option to sunview(l). 

The events KBD_USE and KBD_DONE parallel the locator events 
L0C_WINENTER and LOC_WINEXIT, respectively. KBD_USE indicates that 
your window now has the keyboard focus and KBD_DONE indicates that your 
window no longer has it. 

If the user presses and releases the I Stop 1 key, an event with the code 
WIN_STOP will be sent to the window under the cursor. 31 In addition, a 
SIGURG signal is sent to the window’s process. Your application can use the 
1 Stop I key by clearing a stop flag and setting a SIGURG interrupt handler 32 
before entering a section of code that might, from the user’s perspective, take a 
long time. If your SIGURG handler is called, set the stop flag and return. In the 
code that is taking a long time, query the stop flag whenever convenient When 
you notice that the stop flag has been set, read the event, then gracefully ter¬ 
minate your long operation. 

The function keys in the VUID define an idealized standard layout that groups 
keys by location: 15 left, 15 right, 15 top and 2 bottom. 33 

The event codes associated with the function keys are KEY_LEFT (i), 
KEY_RIGHT (i) and KEY_TOP (i) , where i ranges from 1 to 15. 

If you specifically ask for a function key event code, then that event code will be 
passed to your event procedure. 

If you don’t specifically ask for a given function key event code, then when the 
user presses that function key you will get an escape sequence instead of the 
function key event code (assuming ASCII events have been enabled). For physi¬ 
cal keystations that are mapped to cursor control keys, events with codes that 
correspond to the ANSI X3.64 7-bit ASCII encoding for the cursor control func¬ 
tion are transmitted. For physical keystations mapped to other function keys, 
events with codes that correspond to an ANSI X3.64 user-definable escape 
sequence are transmitted. 


31 WIN_STOP only works when enabled in the PICK event mask and not in the KBD event mask. 

32 See notify_set_signal_func () in in Chapter 17, The Notifier 

33 The actual position of the function keys on a given physical keyboard may differ — see kbd(5) for details 
on various keyboards. 
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Shift Key Events 


Semantic Events 


Other Events 


Applications can notice when a shift key changes state by enabling events with 
the following codes: SHIFT_LEFT, SHIFT_RIGHT, SHIFT_CTRL, 
SHIFT_META, SHIFT_L0CK and SHlFT_CAPSLOCK. Although these codes 
allow you to treat one or more shift key as function-invoking keys, this is not 
recommended. Instead of watching for the event directly, you should query the 
state of the shift keys via the macros described on the next page. 

Release 4.0 of the SunOS introduces a new type of event. These events are 
called action events and represent some old and many new functions in the win¬ 
dow system. They are similar to the old events in that they are mapped to 
specific keys on the keyboard. That is, certain combinations of keystrokes in 
SunView correspond to high-level action events. For example, pressing the 
1 Copy ] key copies the current selection to the Clipboard in text subwindows, 
panels and tty subwindows. 

Action events differ from the old events in that applications can directly express 
interest in the high-level action, “Copy the selection to the Clipboard” rather than 
in the low-level, “The L6 key was pushed”. These events appear in Table 6-1 
with the prefix ACTI0N_. Applications should use action events, because left- 
handed users can assign I Copy I to a different key, and in the future users will be 
allowed to tie high-level events to arbitrary key combinations. 

Your application may receive events which don’t fall into any of the classes 
described above. For example, a non-standard input device, such as a second 
mouse, may emit its own types of events. Also, a software object may communi¬ 
cate with other software objects via events, as is the case when a scrollbar sends a 
SCROLL_REQUEST to a panel or a canvas. 

In general, your event procedure should not treat such unexpected events as 
errors. They can simply be ignored. 
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6.5. Event Descriptors Events have been further grouped into descriptors. Descriptors describe classes 

of events such as all ASCII events, all mouse buttons, all top function keys, and 
so on. You will use these descriptors to set input masks, described in Section 6.7 
Enabling and Disabling Events 

The descriptors are summarized in the following table. 

Table 6-3 Event Descriptors 


Event Descriptor 

Explanation 

WIN_NO_EVENTS 

Clears input mask — no events will be accepted. Note: the 
effect is the same whether used with a consume or an 
ignore attribute. A new window has a cleared input mask. 

WIN_ASCII_EVENTS 

All ASCD events. ASCII events that occur while the META 
key is depressed are reported with codes in the META range. 

In addition, cursor control keys and function keys are 
reported as ANSI escape sequences: a sequence of events 
whose codes are ASCII characters, beginning with <ESC>. 

WIN_IN_TRANSIT_EVENTS 

Enables immediate LOC_MOVE, 

LOCJWINENTER, and 

LOC__WINEXIT events. Pick mask only. Off by default 

WIN_LEFT_KEYS 

The left function keys, KEY_LEFT(1) — KEY_LEFT(15). 

WIN_MOUSE_BUTTONS 

Shorthand for MS_RIGHT, 

MS_MIDDLE 


and MS_LEFT. 

Also sets or resets WIN_UP__E VENTS. 

WIN_RIGHT_KEYS 

The right function keys, KEY_RIGHT(1) — KEY_RIGHT(15). 

WIN_TOP_KEYS 

The top function keys, KEY_TOP(l) — KEY_TOP(15). 

WIN_UP_ASCII_EVENTS 

Causes the matching up transitions to normal 

ASCII events to be reported — if you see an ’a’ 
go down, you’ll eventually see the matching *a’ up. 

WIN_UP_EVENTS 

Causes up transitions to be reported for button 
and function key events being consumed. 


Input may be controlled using input focus and input mask. The input focus is the 
window that is currently receiving input. The input mask specifies which events 
a window will receive and which events a window will ignore. This section 
introduces these concepts and gives the algorithm used by the window system to 
decide which window will receive a given input. 


6.6. Controlling Input in a 
Window 
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Input Focus 


Input Mask 


SunView supports two types of focus models, a single focus model and a split 
focus model. 

The single focus model specifies that all input, no matter which input device it 
came from, goes to the same window. The split input focus lets the user control 
the pick input focus and the keyboard input focus separately. 

The word pick comes from the general graphics term pick device, which is a user 
input device that allows you to move a cursor on the screen and then click a but¬ 
ton to choose a point on the screen. The most common pick devices are the 
mouse, light pen and graphics tablet. 

Under the split input focus model, mouse clicks and keystrokes may be distri¬ 
buted to different windows. This makes some operations easier for the user. For 
example, the user can select text in one window and move it to another window 
without having to position the cursor over the destination window. 

In general, the user controls the keyboard focus by using specific button clicks 
and controls the pick focus by moving the mouse. Sometimes, it is appropriate 
for input focuses to be under program control. Generally you should only change 
an input focus based on some explicit and predictable user action. 

You can indicate that you want a window to become the keyboard focus by set¬ 
ting the WlN_KEYBOARD_FOCUS attribute to TRUE. Note that this is only a 
hint to the window system. If the keyboard focus is tied to the pick focus, then 
this call has no effect. The target window might also refuse the keyboard focus 
request generated by this call (see KBD_REQUEST under Window Events above). 
You can set the pick focus via the wiN_MOUSE_XY attribute, which sets the 
mouse cursor to a particular position within a window. 

For example, the call 

- \ 

window_set(win, WIN_MOUSE_XY f 200, 300, 0); 

V____y 


sets the cursor to the window-relative position (200, 300) and sets the pick focus 
to win. 

An input mask specifies which events a window will receive and which events it 
will ignore. In other words, an input mask serves as a read enable mask. Each 
window has both a pick input mask, to specify which pick related events it wants, 
and a keyboard input mask, to specify which keyboard related events it wants. 

When a window is the pick focus, its pick mask is used to screen events. When a 
window is the keyboard focus, its keyboard mask is used to screen events. 


This section describes how to specify which events a window will receive and 
which it will ignore. 
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Determining which Window 
will Receive Input 


The Notifier determines which window will receive a given event according to 
the following algorithm: 


□ First, the keyboard input mask for the window which is the keyboard focus 
is checked to see if it wants the event. If so, then it becomes the recipient; 
otherwise the next test is applied. 

□ Second, the pick input mask for the window which is under the cursor is 
checked to see if it wants the event. If several windows are layered under 
the cursor, then the event is tested against the pick input mask of the topmost 
window. If the mask wants the event, then it becomes the recipient; other¬ 
wise the next test is applied. 

□ If the event does not match the pick input mask of the window under the cur¬ 
sor, then the event will be offered to that window’s designee. By default the 
designee is the window’s owner. You can set the designee explicitly by cal¬ 
ling window_set () with the WIN_INPUT_DESIGNEE attribute. 34 

□ If an event is offered unsuccessfully to the root window, it is discarded. 
Windows which are not in the chain of designated recipients never have a 
chance to accept the event. 

□ Occasionally you may want to specify that a given window is to receive all 
events, regardless of their location on the screen. You can do this by setting 
the WIN_GRAB_ALL_INPUT attribute for the window to TRUE. 

□ If a recipient is found, then the locator coordinates are adjusted to the coor¬ 
dinate system of the recipient, and the event is appended to the recipient’s 
input stream. Thus, every window sees a single ordered stream of time- 
stamped input events, which contain only the events that a window has 
declared to be of interest 


34 Note that you must give the WIN DEVICE NUMBER of the window you wish to be the designee, not its 
handle. This is to allow specifying windows in another user process as the input designee. So the following call 
would set win2 to be the designee for win 1: window_set (winl, WIN_INPUT_DESIGNEE, 
window_get (win2, WIN_DEVICE_NUMBER) ) ; 
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6.7. Enabling and You specify which events a window will receive and which it will ignore by set- 

Disabling Events ting the window’s input masks via the following set of attributes: 

Table 6-4 Attributes Used to Set Window Input Masks 


Events Taking a 

Single Code 

Events Taking a Null 
Terminated List 

WI N_C ON S UME_KBD_E VEN T 

WlN_CONSUME_KBD_EVENTS 

WI N_I GNORE_KBD_EVENT 

WIN_IGNORE_KBD_EVENTS 

WIN_CONSUME_PICK_EVENT 

WIN_CONSUME_PICK_EVENTS 

WIN_IGNORE_PICK_EVENT 

WIN_IGNORE_PICK_EVENTS 


The above attributes take as values either event codes such as LOC_MOVE, 
MS_LEFT, KEY_LEFT ( 2 ), and so on, or event descriptors. The attributes in 
the left column, ending in “_EVENT”, take a single code or descriptor, while 
those on the right, ending in “_EVENTS”, take a null terminated list 

Which Mask to Use To enable or disable ASCII events, use the keyboard mask. To enable or disable 

locator motion and button events, use the pick mask. 

Function keys are typically associated with the keyboard mask, but sometimes it 
makes sense to include some function keys in the pick mask — in effect extend¬ 
ing the number of buttons associated with the pick device. For example, in the 
SunView interface the (Again I . 1Undo) . 1 Copy 1 . 1 Paste I . (Tutl . and rFIndl func¬ 
tion keys are associated with the keyboard mask, while the I Stop 1 . 1 Front I . and, 

1 Open I keys are associated with the pick mask. 

Examples The event attributes cause precisely the events you specify to be enabled or dis¬ 

abled — the input mask is not automatically cleared to an initial state. To be 
sure that an input mask will let through the events you specify, first clear the 
mask with the special WlN_NO_EVENTS descriptor. Take, for example, the fol¬ 
lowing two calls: 

window_set(win, WIN_CONSUME_PICK_EVENTS, 

WIN_MOUSE_BUTTONS, LOC_DRAG, 0, 

0 ) ; 

window_set(win, WIN_CONSUME_PICK_EVENTS, 

WIN_NO_EVENT S, WIN_MOUSE_BUTTONS, LOC_DRAG, 0, 

0 ) ; 


The first call adds the mouse buttons and LOC_DRAG to the existing pick input 
mask, while the second call sets the mask to let only the mouse buttons and 
LOC_DRAG through. 
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Canvases by default enable loc_winenter, loc_winexit, loc_move, 
and the three mouse buttons, MS_LEFT, MS_MIDDLE, and MS_RIGHT. 33 You 
could allow the user to type in text to a canvas by calling: 

r -- “ > 

window_set(canvas, WIN_CONSUME_KBD_EVENT, WIN_ASCII_EVENTS, 0) ; 

< _. _' 


Sometime later you could disable type-in by calling: 

---- 

window set (canvas, WIN_IGNORE_KBD_EVENT, WIN_ASCII_EVENTS, 0); 


An application needing to track mouse motion with the button down would 
enable LOC_DRAG by calling: 



You can enable or disable the left, right or top function keys as a group via the 
event descriptors win_LEFT_KEYS, win_RIGHT_keys, or 
WIN TOP_KEYS. Note that if you want to see the up event you must also ask 
for WIN UP EVENTS, as in: 



In order to improve interactive performance, in the default case, windows do not 
receive locator motion events (LOC_wiNENTER, LOC_WINEXIT, and 
LOC_MOVE) until after a L0C_STILL has been generated. If each window 
responds to all of the events that are generated each time the mouse passes over 
the window, then the response time of the system will be slowed down. Each 
window will “wake up” when the mouse passes over it on the way to somewhere 
else on the screen. 

If you want a window to receive all events, even if the mouse is just passing over 
the window without stopping, enable WIN_IN_TRANSIT_EVENTS, with a call 
such as: 



35 Note that the canvas package expects to receive these events, and will not function properly if you disable 
them. 
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Setting the Input Mask as a The attributes WIN_KBD_INPUT_MASK and WIN_PICK_INPUT_MASK allow 
Whole you to get or set an entire input mask. Let’s take the example of a subroutine that 

provides interactive feedback. You can save the input mask on entry to the sub¬ 
routine, set up the mask as appropriate, and restore the original mask before 
returning as follows: 

( -—- 

do_feedback() 

{ " 

Inputmask *saved_mask; 

saved_mask = (Inputmask *) 

window_get(win, WIN_KBD_INPUT_MASK); 

window_set(win, WIN_KBD_INPUT_MASK, saved_mask, 0); 



Keep in mind that the inputmask pointer returned by window_get () points to 
a static structure which is shared by all windows in the application. Getting 
either the keyboard or pick input masks for another window will cause the static 
structure to be overwritten. 


Querying the Input Mask 
State 


You can use window_get () with WlN_CONSUME_PICK_EVENT and 
W IN_C0NS UME_KBD_E VENT to query the state of the input masks. For exam¬ 
ple, the following call will find out whether or not a canvas is accepting 
LOC_DRAGs: 

/-\ 

flag * (int) window_get (canvas, WIN_CONSUME_PICK_EVENT, LOC_DRAG) ; 
V_y 
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6.8. Querying and Setting You can query the state associated with an event using the following macros, all 

the Event State of which take as their only argument a pointer to an Event. 

Table 6-5 Macros to Get the Event State 


Macro 

Returns 

event_action () 

The identifying code of the event The codes are dis¬ 
cussed in the previous section. 36 

event_is_up () 

TRUE if the event is a button or key 
event and the state is up. 

event__i s_down () 

TRUE if the event is a button or key 
event and the state is down. 

event__x () 

The x coordinate of the locator in the window’s 
coordinate system at the time the event occurred. 

event_y() 

The y coordinate of the locator in the window’s 
coordinate system at the time the event occurred. 

event_shiftmask() 

The value of predefined shift-keys 
(described in kbd(5)). Possible values: 

#define CAPSMASK 0x0001 

#define SHIFTMASK OxOOOE 

#define CTRLMASK 0x0030 

#define META__SH IFT__MASK 0x0040 

event_time() 

The event’s timestamp, formatted as a timeval 
struct, as defined in <sys/time .h>. 

event_shift_is_down () 

TRUE if one of the shift keys are down. 

event_ct rl_i s_down () 

TRUE if the control key is down. 

event_meta_is_down () 

TRUE if the meta key is down. 

event__i s_button () 

TRUE if the event is a mouse button. 

event_is_ascii () 

TRUE if the event is in the ASCII range (0 thru 127). 

event_is__meta () 

TRUE if the event is in the META range (128 thru 255). 

event_is__key__left () 

TRUE if the event is any KEY_LEFT (i). 

event_i s_key_right () 

TRUE if the event is any KEY_RIGHT (i). 

event_i s_key_top () 

TRUE if the event is any KEY_TOP (i). 


In addition to the above macros, which tell about the state of a particular event, 
you can query the state of any button or key via the WIN_EVENT_STATE attri¬ 
bute. For example, to find out whether or not the first right function key is down 
you would call: 

---— - — - > 

kl_down = (int) 

window_get(canvas, WIN_EVENT_STATE, KEY_RIGHT(1)); 
s__—- ' 

The call will return non-zero if the key is down, and zero if the key is up. 

The following macros are provided to let you set some of the states associated 
with an event. 

36 event_id() is replaced by event_act ion () However, for compatibility, event_id () will still 
be supported. 
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Table 6-6 Macros to Set the Event State 


Macro 

Effect 


event_set__action (event, code) 
event_set__shiftmask 

set event’s id to code. 


(event, shiftmask) 

set event’s shiftmask to shiftmask. 

Possible values: 


#define CAPSMASK 

0x0001 


#define SHIFTMASK 

OxOOOE 


#define CTRLMASK 

0x0030 


#define META__SHIFT_MASK 

0x0040 

event__set_x (event, x) 

set event’s x coordinate to x. 


event_set_y(event, y) 

set event’s y coordinate to y. 


event_set_time(event, time) 

set event’s timestamp to time. 


event_set_up(event) 

set state of a button event to up. 


event_set_down(event) 

set state of a button event to down. 



6.9. Releasing the Event If an operation generated by an input event is going to take over 5 seconds, then 
Lock call this routine to allow other processes to get input: 37 

void 

window_release__event_lock (window) 

Window window; 


6.10. Reading Events There are times when it is appropriate to go get the next event yourself, rather 

Explicitly than waiting for it to come through the normal event stream from the Notifier. In 

particular, when tracking the mouse with an image which requires significant 
computation, it may be desirable to read events until a particular action, such as a 
mouse button up, is detected. To read the next input event for a window, bypass¬ 
ing the Notifier, use the function: 

int 

window__read_event (window f event) 

Window window; 

Event *event; 

window_read_event () fills in the event structure, and returns 0 if all went 
well. In case of error, it sets the global variable errno and returns —1. 

window_read_e vent () can be used in either a blocking or non-blocking 
mode, depending on how the window has been set up. 38 


37 For more details see the section on synchronization in the Workstations chapter of the SunView 1 System 
Programmer’s Guide. 

38 window_read_event() is the high-level library standard function equivalent of input_readevent() in the 
low-level library. For further information, see Section 5.6, Reading Input in the SunView 1 System 
Programmer s Guide. 
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Note that if you read events in a canvas subwindow yourself, you must translate 
the event’s location to canvas space by calling canvas_event (): 

event_in_canvas_space = canvas_event(canvas, event); 
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Imaging Facilities: Pixwins 


Material Covered 

This chapter describes the pixwin which is the construct you use to draw or 
render images in SunView. The most basic use of pixwins is to draw in a canvas 
subwindow. 

In addition to basic pixwin usage, this chapter covers: 

□ How to boost your rendering speed by locking and batching 

□ How to use regions for clipping 

□ How to manipulate the colormap 

□ How to use the plane groups 

Related Documentation 

This chapter is addressed primarily to programmers who write simple applica¬ 
tions using canvas subwindows. For lower level details, see the chapter on 
Advanced Imaging in the SunView System Programmers Guide. 

The pixwin drawing operations do not directly support high-level graphics opera¬ 
tions such as shading, segments, 3-D, etc. If your application requires these, then 
you should consider some graphics package such as SunGKS, SunCore, or 
SunCGI. All of these will run in windows (see the SunCore Reference Manual 
and SunCGI Reference Manual for more information). 

Header Files 

The definitions necessary to use pixwins are in the header file 
<sunwindow/pixwin. h>, which is included by 

<sunwindow/window_hs . h>, which in turn is included by default when 
you include <suntool/sunview. h>. 

Summary Listing and Tables 

To give you a feeling for what you can do with pixwins, the following page con¬ 
tains a list of the available pixin functions and macros. Many of these are dis¬ 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the pixwin summary tables in Chapter 
19, SunView Interface Summary : 

□ the Pixwin Drawing Functions and Macros table begins on page 356; 


□ the Pixwin Color Manipulation Functions table begins on page 360. 
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_ Pixwin Drawing Functions and Macros _ 

pw_batch(pw, n) 
pw_batch_of f (pw) 
pw_batch_on (pw) 

pw_batchrop(pw, dx, dy, op, items, n) 
pw_char(pw, x, y, op, font, c) 
pw_close(pw) 

pw_copy(dpw, dx, dy, dw, dh, op, spw, sx, sy) 
pw__get (pw, x, y) 
pw_get_region_rect (pw, r) 

pw_line(pw, xO, yO, xl, yl, brush, tex, op) 
pw__lock(pw, r) 
pw_pfsysclose () 
pw_pfsysopen() 

pw_jpolygon__2 (pw, dx, dy, nbds, npts, vlist, op, spr, sx, sy) 
pw_j>olyline (pw, dx, dy, npts, ptlist, mvlist, brush, tex, op) 
pw_polypoint(pw, dx, dy, npts, ptlist, op) 
pw_put(pw, x, y, value) 

pw_read(pr, dx, dy, dw, dh, op, pw, sx, sy) 
pw_region(pw, x, y, width, height) 
pw_replrop(pw, dx, dy, dw, dh, op, pr, sx, sy) 
pw_reset(pw) 

pw_rop(pw, dx, dy, dw, dh, op, sp, sx, sy) 
pw_set_region_rect (pw, r, use_same_j?r) 
pw_show(pw) 

pw__stencil (dpw, dx, dy, dw, dh, op, stpr, stx, sty, spr, sx, sy) 

pw_text(pw, x, y, op, font, s) 

pw_traprop(pw, dx, dy, t, op, pr, sx, sy) 

pw_ttext(pw, x, y, op, font, s) 

pw__unlock (pw) 

pw_vector(pw, xO, yO, xl, yl, op, value) 
pw__write (pw, dx, dy, dw, dh, op, pr, sx, sy) 

pw_writebackground(pw, dx, dy, dw, dh, op)_ 


Pixwin Color Manipulation Functions 

pw blackonwhite(pw, min, max) pw_getcolormap(pw, index, count. 

pw_cyclecolormap(pw, cycles. 

index, count) red, green, blue) 

pw_dbl_access (pw) 

pw_getdefaultcms (cms, map) 

pw__dbl_f lip (pw) 

pw_putattributes(pw, planes) 

pw dbl_get(pw, attribute) 

pw_j?utcolormap (pw, index, count. 

pw dbl_release() 

red, green, blue) 

pw_dbl_set(pw, attributes) 

pw reversevideo(pw, min, max) 

pw getattributes(pw, planes) 

p w_s e t cms n ame (p w, cms name) 

pw getcmsname (pw, cmsname) 

pw whiteonblack(pw, min, max) 
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7.1. What is a Pixwin? An image in SunView, whether on the screen or in memory, is composed of dots 

called pixels and is represented internally as a rectangle of such pixels. The pix- 
rect structure is the construct used at a low level to access an image and operate 
on it. You can program at the pixrect level to draw on the screen; this is covered 
in the Pixrect Reference Manual. 

However, in SunView drawing operations are displayed in a window coexisting 
on the screen with other, possibly overlapping windows. Except in certain cir¬ 
cumstances, drawing operations should be “well-behaved,” meaning that they 
should not spill over into other windows and they should not be visible in por¬ 
tions of the window which are covered by other windows. The pixwin is the 
interface through which you operate on the pixels in a particular window. It 
guarantees that the above two conditions will be met. 

Each pixel has a value. On a monochrome display the value is 1 or 0, since the 
pixel can only be on or off, black or white. Such pixels are said to be 7 bit deep. 
On a color display each pixel can have several values corresponding to different 
colors. 

This section summarizes the functions provided for accessing the pixels of a 
pixwin. Most of the pw_* functions described in this section are based on 
corresponding pr_* routines, which are fully documented in the Pixrect Refer¬ 
ence Manual. For full discussion of the semantics of a given pixwin function, 
refer to the discussion of the corresponding pixrect function in the Pixrect Refer¬ 
ence Manual and/or the errata/addenda section of the most recent Release 
Manual. 

In particular the pixrect manual gives useful values for the op argument which 
determines what the result of combining the source and destination pixels will 
be. 

The procedures described in this section will maintain the memory pixrect for a 
retained pixwin. That is, they perform their operation on the data in memory, as 
well as on the screen. 

Obtaining the Window’s All of these procedures require the pixwin of the window you are drawing in as 

Pixwin an argument. To draw in a canvas, you use the pixwin that is returned by the 

procedure: 

Pixwin *pw; 

canvas_pixwin(canvas); 

Canvas canvas; 

Look at the example in Section 5.1, Creating and Drawing into a Canvas, to see 
how canvas_pixwin () is used. 

The pixwin is also available as the value of the CANVAS_PIXWIN attribute of 
the canvas subwindow. 39 


39 Aside from the canvas pixwin, all windows, regardless of type, have a pixwin which is available as the 
value of WIN_P IXWIN. However, most applications should not need to explicitly write pixels into other types 
of windows. 


7.2. Accessing a Pixwin’s 
Pixels 
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Write Routines 


Basic RasterOp Operations 


Other Raster Operations 


The following routines allow you to draw areas, backgrounds, vectors, text, 
polygons, lines, and polylines in a pixwin. 

The following are the basic low-level raster operations that draw on the screen. 
They are common to many imaging systems. 

pw_write(pw, dx, dy, dw, dh, op, pr, sx, sy) 

— or — 

pw_rop(pw, dx, dy, dw, dh, op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 


pw_wr it e () and pw_rop () are different names for the same procedure. 

They perform the indicated rasterop (op) from the source pixrect to the destina¬ 
tion in the pixwin. Pixels are written to the rectangle defined by dx, dy, dw, and 
dh in the pixwin pw using rasterop function op. dx and dy are the position of 
the top left-hand comer of the rectangle, and dw and dh are the width and height 
of the rectangle. They are copied from the rectangle with its origin at sx, sy in 
the source pixrect pointed to by pr. 

pw_wr ite () is essential for many window system operations such as scrolling 
a window, drawing frames and borders, and drawing an icon on the screen. 

The routines in this section are variations on the basic rasterop routine. 

pw_writebackground(pw, dx, dy, dw, dh, op) 

Pixwin *pw; 

int dx, dy, dw, dh, op; 


pw_writebackground () uses a conceptually infinite set of pixels, all of 
which are set to zero, as the source. It is often used to clear a canvas pixwin 
before drawing a new image. 40 

The following routine draws a pixel of value at ( x, y) in the addressed 
pixwin: 

pw_j>ut (pw, x, y, value) 

Pixwin *pw; 

int x, y, value; 

Using this routine to draw is very slow and should be avoided. If you use it, be 
sure to read the later sections on batching and locking . 


40 Canvases will automatically clear damaged areas if they are set not to be retained, or if the attribute 
CANVAS AUTO CLEAR is set. See Chapter 5, Canvases , for more information. 
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There is a similar routine to draw many pixels in a single call, 
pw_J5olypoint(pw, dx, dy, npts, ptlist, op) 


Pixwin 

int 


*• 


pw; 

dx, dy, npts; 


struct pr_j50S *ptlist; 


int 


op; 


All npts points in the array ptlist are drawn in the pixwin pw starting at the 
offset dx, dy under the control of the op argument. 

The next routine draws a vector of pixel value from (xO, yO) to (xl, yl) in the 
addressed pixwin using rasterop op: 

pw_vector(pw, xO, yO, xl, yl, op, value) 

Pixwin *pw; 

int xO, yO, xl, yl, op, value; 

To replicate a pattern in a pixrect onto a pixwin, use: 

pw_replrop(pw, dx, dy, dw, dh, op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 


pw__r eplrop () replicates a small “patch” of pattern in a pixrect onto an entire 
pixwin. It is often used to draw a patterned background in a window, such as the 
root gray pattern in sunview(l). Standard patterns, created by iconedit(l), 
may be found in /usr/include/images/square_* .pr. 


Text Routines 


The following two routines write a string of characters and a single character, 
respectively, to a pixwin, using rasterop op as above: 


pw_text(pw, x, y, op, font, s) 


Pixwin *pw; 
int x, y, op; 

Pixfont *font; 
char *s; 


* 


pw_char(pw, x, y, op, font, c) 


Pixwin *pw; 
int x, y, op; 

Pixfont *font; 
char c; 
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These text rendering routines are distinguished by their own coordinate system: 
the destination is given as the left edge and baseline of the first character. The 
left edge does not take into account any kerning (character position adjustment 
depending on its neighbors), so it is possible for a character to have some pixels 
to the left of the x-coordinate. The baseline is the y-coordinate of the lowest 
pixel of characters without descenders, ‘L’ or ‘o’ for example, so pixels will fre¬ 
quently occur both above and below the baseline in a string. 41 

font may be NULL in which case the system font is used. 

The system font is reference counted and shared between software packages. 
The following routines are provided to open and close the system font: 42 

Pixfont * 
pw_pfsysopen() 

pw_pfsysclose() 

The following routine: 


ttext(pw. 

x. 

y, op. 

Pixwin 

*pw; 


int 

x. 

y, op; 

Pixfont 

*font; 

char 

*s; 



Batching and Stenciling 
Routines 


is just like pw_t ext () except that it writes transparent text. Transparent text 
writes the shape of the letters without disturbing the background behind it. This 
is most useful with color pixwins. Monochrome pixwins can use pw_text () 
and a pex_src I pix.dst op, which is faster. 


Applications such as displaying text perform the same operation on a number of 
pixrects in a fashion that is amenable to global optimization. The batchrop pro¬ 
cedure is provided for these situations: 


pw_batchrop(pw, dx, 
Pixwin 


dy, op, items, n) 
*pw; 


int dx, dy, op, n; 

struct pr_prpos items []; 4 ^ 

Stencil operations are like raster ops except that the source pixrect is written 
through a stencil pixrect which functions as a pixel-by-pixel write enable mask. 
The indicated raster operation is applied only to destination pixels where the 
stencil pixrect stpr is non-zero; other destination pixels remain unchanged. 


41 A font to be used in pw text () is required to have the same pc home. y and character height for all 
characters in the font. 

42 The system font can also be obtained by calling pf_default (). 

43 The structure of pr_prpos is given in Appendix C of the Pixrect Reference Manual. 
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pw_stencil(dpw, dx, dy f dw, dh, op, stpr, stx, 
sty, spr, sx, sy) 

Pixwin *dpw; 

Pixrect *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 


Drawing Polygons 


Drawing Curved Shapes 


Drawing Lines 


The following macro draws a polygon within a pixwin: 

pw_j>olygon_2(pw, dx, dy, nbds, npts, vlist, op, spr, sx, sy) 
Pixwin *pw; 

int dx, dy, nbds, op, sx, sy; 

int npts In¬ 

struct pr_jpos *vlist; 

Pixrect *spr; 

You can create a polygon filled with a solid or textured pattern. 

pw_traprop () is a pixwin operation analogous to pw_rop (), which 
operates on a trapezon rather than a rectangle: 

pw_traprop(pw, dx, dy, t, op, pr, sx, sy) 

Pixwin *pw; 

struct pr__trap t; 

Pixrect *pr; 

int dx, dy, op, sx, sy; 

pw__traprop () writes the source pixrect pr into the destination pixwin pw via 
the operation op. The output is clipped to the trapezon t. 


The following routine draws a solid or textured line between two points with a 
“brush” of a specified width: 

pw_line(pw, xO, yO, xl, yl, brush, tex, op) 

Pixwin *pw; 

int xO, yO, xl, yl, op; 

struct pr_brush *brush; 
struct pr_texture *tex; 


There is a similar routine to draw several noncontiguous line segments between a 
set of points: 


pwjpolyline(pw, dx, 
Pixwin 
int 

struct pr_pos 
u_char 

struct pr_brush 
struct pr_texture 


dy, npts, ptlist, mvlist 
*pw; 

dx, dy, npts, op; 
*ptlist; 

*mvlist; 

*brush 
*tex; 


brush. 


tex. 


op) 
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Read and Copy Routines 


7.3. Rendering Speed 


The following routines use the pixwin as a source of pixels. To get the value of 
the pixel at (x, y) in pixwin pw call: 

int 

pw_get(pw, x, y) 

Pixwin *pw; 
int x, y; 

To read pixels from a pixwin into a pixrect call: 

pw_read(pr, dx, dy, dw, dh, op, pw, sx, sy) 


Pixwin 

*pw; 

int 

dx, dy, dw, dh, op, sx, sy; 

Pixrect 

*pr; 


This routine reads pixels from pw starting at offset ( sx, sy), using rasterop op. 
The pixels are stored in the rectangle with its origin at dx, dy of width dw and 
height dh in the pixrect pointed to by pr. 

When the destination, as well as the source, is a pixwin, use: 

pw_copy(dpw, dx, dy, dw, dh, op, spw, sx, sy) 

Pixwin *dpw, *spw; 

int dx, dy, dw, dh, op, sx, sy; 

dpw and spw must be the same pixwin. Also, only horizontal or vertical copies 
are supported. 

These read and copy routines fail if they try to read from a portion of a non- 
retained pixwin which is hidden, and therefore has no pixels. Therefore it is con¬ 
sidered advanced usage to call them on a non-retained pixwin; refer to the section 
entitled Handling Fixup in the SunView 1 System Programmer’s Guide. 


Making correct and judicious use of explicit display locking and/or batching is 
important for getting the best display speed possible. 

There are two major impediments to you getting the best possible display render¬ 
ing speed. The first is display locking , which prevents window processes from 
interfering with each other in several ways: 

□ Raster hardware may require several operations to complete a change to the 
display; one process’ use of the hardware should be protected from interfer¬ 
ence by others during this critical interval. 

□ Changes to the arrangement of windows must be prevented while a process 
is painting, lest an area be removed from a window as it is being painted. 

□ A software cursor that the window process does not control (the kernel is 
usually responsible for the cursor) may have to be removed so that it does 
not interfere with the window’s image. 

Display locking is relatively expensive compared to the time it takes to do simple 
display operations. Thus you can reduce your display time by reducing the 
number of times that you have to acquire the display lock. The subsection below 
titled Locking explains how to do this. 
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Locking 




The second major impediment to maximum display speed is the use of retained 
pixwins. It is obvious that if you have to write to the screen and to memory for 
every display operation that it will take longer than writing to only one place. 
Thus, there is a mechanism, called pixwin batching which allows you to write 
only to memory and then refresh the screen with a quick raster operation from 
memory. The subsection entitled Batching explains how to use batching. 

Locking allows a client program to obtain exclusive use of the display. If the 
client program does not obtain an explicit lock, the window system will. For 
example, if your application is going to draw one hundred lines it can either 
explicitly lock the display once, draw the lines, and unlock explicitly, or it can 
ignore locking and simply draw the lines. In the latter case, the window system 
will perform locking and unlocking around each drawing operation, acquiring 
and releasing the lock one hundred times instead of once. 

NOTE For efficiency’s sake, application programs should lock explicitly around a body 
of screen access operations. 

You can acquire a lock by calling the macro: 

pw_lock(pw, r) 

Pixwin *pw; 

Rect *r; 

pw is the pixwin to be used for the output; r is the rectangle in the pixwin’s coor¬ 
dinate system that bounds the area to be affected. See The Rect Structure in 
Chapter 4, Using Windows, for an explanation of the Rect structure. 
pw_lock () blocks if the lock is unavailable (if, for example, another process 
currently has the display locked). 

When the cursor is on the surface where drawing occurs, if the pixwin is locked 
with pw_lock (), sometimes the region in which the cursor rect resides is not 
drawn to. This results in an empty region (16 x 16 pixels) when the cursor is 
moved. The image is put to its correct state when it is redisplayed. 

Lock operations for a single pixwin may be nested; inner lock operations merely 
increment a count of locks outstanding and are thus very lightweight. Their 
affected rectangles must lie within the rectangles affected by the original lock. 

To decrement the lock count, call: 

pw_unlock(pw) 

Pixwin *pw; 

When the lock count reaches 0, the lock is actually released. 

Since locks may be nested, it is possible for a client procedure to find itself, espe¬ 
cially in error handling, with a lock which may require an indefinite number of 
unlocks. To handle this situation cleanly, another routine is provided. The fol¬ 
lowing macro sets pw’s lock count to 0 and releases its lock: 

pw_reset(pw) 

Pixwin *pw; 
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Batching 


Acquisition of a lock has the following effects: 

□ If the cursor is in conflict with the affected rectangle, it is removed from the 
screen. While the screen is locked, the cursor will not be moved in such a 
way as to disrupt any screen accessing. 

□ Access to the display is restricted to the process acquiring the lock. 

□ Modification of the database that describes the positions of all the windows 
on the screen is prevented. 

□ The clipping information for the pixwin is validated and, if necessary, 
updated. 

□ In the case of a non-retained pixwin with only a single rectangle visible, the 
internals of the pixwin mechanism can be set up to bypass the pixwin 
software by going directly to the pixrect level on subsequent display opera¬ 
tions. 

While it has the screen locked, a process should not: 

□ do any significant computation unrelated to displaying its image. 

o invoke any system calls, including other I/O, which might cause it to block. 

□ invoke any pixwin calls except pw_unlock () and those described in the 
previous section. Accessing a Pixwin’s Pixels. In any case, the lock should 
not be held longer than about a quarter of a second, even following all these 
guidelines. 

When a display lock is held for more than two seconds of process virtual time, 
the lock is broken. However, the offending process is not notified by signal, 
because a process shouldn’t be aborted for this infraction. Instead, a message is 
displayed on the console. 

Batching allows you to write only to the memory pixrect of a retained pixwin and 
then refresh the screen with the memory pixrect’s contents at specific times. If 
you do not explicitly batch when using a retained pixwin, the window system 
will write to both the display and memory on every display operation. 

Considering the same example used for locking above, if your application pro¬ 
gram has a retained pixwin and is going to draw one hundred lines, it can either 
explicitly start a batch, draw the lines, and end the batch explicitly, or it can 
ignore batching and simply draw the lines. In the latter case, the window system 
will draw the lines two hundred times instead of one hundred times. 

NOTE For efficiency’s sake, application programs should batch explicitly around a 

body of screen access operations when using a retained pixwin. 
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Two macros are provided to control batching: 

pw_batch_on (pw) 

Pixwin *pw; 

pw_batch_off(pw) 

Pixwin *pw; 


pw_batch_on () starts a batch; pw_batch_off () refreshes the screen with 
the portion of the memory pixrect that has changed. While batching, the pixwin 
internally maintains a rectangle that describes which pixels in the memory pix¬ 
rect need to be transferred to the screen at the end of the batch. 

NOTE Don’t turn batching on and leave it on, as this causes problems with scrolling. 
The recommended use is batch_on () (draw something in window) 
batch_off(). 

While in the middle of batching, your code might reach a point at which you 
would like the screen to be updated. The following macro refreshes the screen, 
but otherwise doesn’t change the batching mode: 

pw_show(pw) 

Pixwin *pw; 

Unlike locking operations, batch operations for a single pixwin do not nest. 

Thus, each batching routine in this section affects the batching mode/status. 

These three macros — pw_batch_on (), pw_bat ch_of f () and 
pw_show () — all call the routine pw_batch () which actually implements 
the batching mechanism. You can call pw_batch() directly to tell the batch¬ 
ing mechanism to refresh the screen after every n display operations. 

pw_batch(pw, kind) 

Pixwin *pw; 

Pw_batch_type kind; 

Because the routine does more than one kind of thing, calling it is a little tricky, 
kind is the kind of batching requested. You use the following macro to convert 
n,the number of display operations you want to be batched before a refresh, to a 
Pw_batch_type: 

♦define PW_OP_COUNT(n) ((Pw_batch_type)(n)) 

So, to have batching and ensure the image on-screen is refreshed after every n 
operations, call: 

pw_batch(pw, PW_OP_COUNT(n)); 

Clients with a group of screen updates to do can gain noticeably by doing the 
group as a batch. Also, the locking overhead, discussed above, will only be 
incurred when the screen is refreshed. An example of such a group is displaying 
a screen full of text, or a series of vectors with pre-computed endpoints. 

In considering how to do batching, it’s a good idea to be sensitive to how long 
the user is staring at a blank screen or an old image, and adjust the rate of screen 
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refresh accordingly. 

Locking and Batching There are situations in which batching around locking calls makes sense. Con- 

Interaction sider that 

□ while batching, locking calls are a no-op; 

□ if a pixwin is not retained, batching calls are a no-op. 

Thus, if your application has a switch to run retained or not, it makes good sense 
to batch around locking calls. If you batch around locking calls then your appli¬ 
cation gets the benefit of batching if running retained and the benefit of locking if 
running non-retained. 

Locking around batches, on the other hand, is not very efficient. 

7.4. Clipping With Regions You can use pixwins to clip rectangular regions within a window’s own rec¬ 
tangular area. The region operation creates a new pixwin that refers to an area 
within an existing pixwin: 

Pixwin * 

pw_region(pw, x, y, w, h) 

Pixwin *pw; 

int x, y, w, h; 


pw is the source pixwin; x, y, w and h describe the rectangle to be included in 
the new pixwin. The upper left pixel in the returned pixwin is at coordinates 
(0,0); this pixel has coordinates ( x, y) in the source pixwin. 

If the source pixwin is retained, the new region will be retained as well. How¬ 
ever, the region refers back to the bits of memory pixrect of the source pixwin 
when accessing the image. 

To change the size of an existing region, call: 

int 

pw_set__region_rect (pw, r, use_same_pr) 

Pixwin *pw; 

Rect *r; 

unsigned use_same_pr; 

The position and size of the region pw are set to the rect *r; a return value of -1 
indicates failure. This is more efficient then destroying the old region and creat¬ 
ing a new one. The use_same_pr flag should be set to 0 if you want a new 
retained pixrect allocated for the region that is the size of the region. 

To determine the size of an existing region, call: 

int 

pw_get_region_rect (pw, r) 

Pixwin *pw; 

Rect *r; 
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7.5. Color 


Introduction to Color 


The Colormap 


*r is set to the size and position of the region pw. 

When finished with a region, you should release it by calling: to: 

pw_close(pw) 

Pixwin *pw; 

This routine frees any dynamic storage associated with the pixwin, including its 
retained memory pixrect, if any. If the pixwin has a lock on the screen, it is 
released. 

NOTE You should close any regions before closing the pixwin containing the regions. 

The dicussion which follows is divided into three sections: 

□ Introduction to Color, which introduces the concepts of the colormap and 
colormap segments, 

□ Changing the Colormap, which describes how to change a colormap seg¬ 
ment, and 

□ Using Color, which describes how to make color applications compatible 
with monochrome and grayscale screens, and how to perform smooth anima¬ 
tion by using double buffering. 

Just as there must be arbitration between different windows to decide what is 
displayed on the screen when several windows overlap, there must likewise be 
some process of allocation when several windows want to display different sets 
of many colors all at once. To understand how this works you need to know how 
color is handled. 

The pixels on a color display are not simply on or off; they take many different 
values for different colors. On all current Sun color displays 44 each pixel has 8 
bits. Such an “8 bit deep” pixel can have any value from 0 to 255. The value in 
each pixel helps to determine what color appears in that dot on the screen, but it 
is not in a one-to-one correspondence with die color displayed; otherwise Sun 
color displays would only be able to display 256 different colors. 

Instead, the value of the pixel serves as an index into the colormap of the display. 
The colormap is an array of 256 colormap entries. The colormap entry for each 
index drives the color that is actually displayed for the corresponding pixel value. 
A colormap entry consists of 8 bits of red intensity, 8 bits of green intensity and 
8 bits of blue, packaged into the following structure: 

struct singlecolor { 

u_char red, green, blue; 

}; 

Hence a Sun color display is capable of displaying over 16 million colors 
(because each colormap entry has 24 bits) but can only display 256 colors simul¬ 
taneously (because there are only 256 colormap entries). 


44 See cgone(4S), cgtwo(4S) and cgfour(4S) in the UNIX Interface Overview manual. 
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A Colormap Example 


Changing the Colormap 


Colormap Segments 


Suppose that in a group of pixels on the screen, some have the value 0 while oth¬ 
ers have the value 193. All pixels with the same value will be displayed in the 
same color. The colormap determines what that color will be. If entry 0 in the 
colormap of the screen is 


red = 250; green =0; blue =3; 

then the pixels with a value of 0 will come out bright red. If entry 0 in the color- 
map is changed to 


red = 1; green = 8; blue = 2; 

then the pixels with a value of 0 will immediately change color to an almost- 
black green. Similarly, entry 193 in the colormap determines what color the pix¬ 
els with a value of 193 will have. 


Because changing the colormap is much faster than redrawing many thousands of 
pixels with a new value, manipulating the colormap is the basis of many graphics 
and animation techniques. For examples of programs that manipulate the color- 
map, run /usr/demo/suncube or /usr/demo/flight. 


Try running spheresedemo -g plus another color program at the same time. 
You will notice that as you move the mouse into the spheresdemo window, 
the colors in the other windows on the display change dramatically. This is 
because hardware is only capable of displaying 256 colors at once. When two 
programs that each want to display 256 different colors are run simultaneously, 
the window system itself must manipulate the colormap. When the cursor enters 
one of the windows, the window system changes the colormap to use the colors 
of that window. 


The window system allows each window to claim a portion of the total available 
colormap entries, called a colormap segment. The colormap segment need not be 
the same in all windows of a tool: frames and subwindows can have different 
colormaps, or can share colormaps (see Sharing Colormap Segments below). If 
the total number of entries in all the colormap segments being requested exceeds 
the limit of 256 at any given time, the window system gives priority to the win¬ 
dow under the cursor, and removes segments belonging to other windows as 
necessary. 

The window system loads colormap segments at arbitrary locations within the 
colormap. To the application program, this indirection is transparent. The rou¬ 
tines that access a pixwin’s pixels do not distinguish between windows which use 
colormap segments and those which use the entire colormap. 

NOTE While you can have multiple pixwins within a window, there is only one color- 
map segment per window. A separate colormap for each pixwin in a window is 
not supported. This limitation should only be of interest if you are using pixwin 
regions (described in the SunView System Programmer’s Guide). 
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Background and Foreground 


Default Colormap Segment 


Changing Colors from the 
Command Line 


Sharing Colormap Segments 


Every colormap segment has two distinguished values, its background and fore¬ 
ground. The background color is defined as the value at the first position of a 
colormap segment; the foreground color is the value at the last position. 

The first pixwin created for a window sets the background and foreground of the 
window to be those of the default colormap segment. This is the monochrome 
colormap segment defined in 

<sunwindow/cms_mono. h>. Subsequent pixwins created for the window 
inherit the background and foreground of the window. 

The user can modify the default colormap for all applications by invoking - 
sunview with the -F and -B command line arguments. 45 The user can also 
change the default colormap segment on a per-application basis by invoking the 
application with certain flags. The -Wf flag sets the foreground color, -Wb sets 
the background color, and -Wg specifies that the colormap of the frame will be 
inherited by the frame’s subwindows. 

The equivalent frame attributes for these flags are 
FRAME_FOREGROUND_COLOR, FRAME_BACKGROUND_COLOR, and 
FRAME__INHERIT_COLORS. 

It is possible for different processes to share a single colormap segment. For 
some applications, you want to guarantee that your colormap segment is not 
shared by another process. For example, a colormap segment to be used for ani¬ 
mation, as described later in the section on Double Buffering, should not be 
shared. The way to ensure that a colormap segment will not be shared by another 
window is to give it a unique name. A common way to generate a unique name 
is to append the process’ id to a more meaningful string that describes the usage 
of the colormap segment. 

If a colormap segment’s usage is static in nature, then it pays to use a shared 
colormap segment definition, since colormap entries are scarce. Windows, in the 
same or different processes, can share the same colormap by referring to it by the 
same name. 

There are three basic types of shared colormap segments: 

□ A colormap segment used by a single program. Sharing occurs when multi¬ 
ple instances of the same program are running. An example of such a pro¬ 
gram is a color terminal emulator in which the terminal has a fixed selection 
of colors. 

□ A colormap segment used by a group of highly interrelated programs. Shar¬ 
ing occurs whenever two or more programs of this group are running at the 
same time. An example of such a group is a series of CAD/CAM programs 
in which it is common to have multiple programs running at the same time. 


45 This is not true fora Sun-3/110 and other machines with cgfour frame buffers, due to their use of an 
overlay plane to implement most monochrome windows. 


Background and Foreground 


Default Colormap Segment 


Changing Colors from the 
Command Line 


Sharing Colormap Segments 
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Example: showcolor 


□ A coloimap segment used by a group of unrelated programs. Sharing occurs 
whenever two or more programs of this group are running. An example of 
such a colormap segment is the default coloimap, cms_monochrome, 
defined in <sunwindow/ cms_mono. h>. Other common useful color- 
map segment definitions that you can use and share with other windows 
include cms_rgb. h, cms_grays. h, cms_mono. h, and 
cms rainbow. h, found in <sunwindow/cms_* . h>. 


The program on the following page shows the actual colors in the display’s 
colormap. It should help you see how the window system manages the color- 
map. Run this program soon after bringing up sunview, then run several color 
graphics programs such as the demos mentioned earlier. Try bringing up dif¬ 
ferent windows with different foreground and background colors, as in: 



/* 

* showcolor.c 

* Draw a grey ramp that graphically shows the colormap 

* segment activity of the environment when the cursor 

* is NOT in the canvas of this tool. 

*/ 

♦include <suntool/sunview.h> 

♦include <suntool/canvas.h> 


♦define CMS_SIZE 256 

♦define CAN HEIGHT 10 


main(argc, argv) 

char **argv; 

{ 

Frame 

Canvas 

register Pixwin 
register int 
u char 


frame; 

canvas; 

*pw; 

i; 

red[CMS_SIZE], 
green[CMS_SIZE], 
blue[CMS_SIZE]; 


/* Create frame and canvas */ 
frame = window_create(0, FRAME, 

FRAME_LABEL, a rgv[0], 
FRAME_ARGS, argc, argv, 
0 ); 

canvas = window_create (frame, CANVAS, 

WIN__HEIGHT, CAN_HEIGHT, 
WIN_WIDTH, 2 * CMS_SIZE, 
0 ); 

window_fit (frame) ; 

pw = canvas ^pixwin(canvas); 

/* Initialize colormap to grey ramp */ 

(?) 
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for (i = 0; i < CMS_SIZE; i++) 

red[i] = green[i] = blue[i] = i; 
pw_setcmsname (pw, "showedor") ; 

pw_putcolormap(pw, 0, CMS_SIZE, red, green, blue); 

/* Draw ramp of colors */ 
for (i = 0; i < CMS_SIZE; i++) 

pw_rop(pw, i*2, 0, 2, CAN_HEIGHT, 

PIX_SRC | PIX_C0L0R(i), (Pixrect *)0, 0, 0); 
window_main_loop (frame) ; 
exit(0); 


Manipulating the Colormap 


The following sections document the routines that implement the techniques 
described above. 


To change a window’s colormap segment, you must: 

1. Name the colormap segment with pw setcmsname (). 

2. Set the size of the segment by loading the colors with 
pw_putcolormap(). 

It is important that these two steps happen in order and together. The call to 
pw_setcmsname () does not take effect until you write at least one color 
value into the colormap with pw_putcolormap (). 

You set and retrieve the name of a colormap segment with these two functions: 

pw_setcmsname(pw, name) 

Pixwin *pw; 

char name[CMS_NAMESIZE]; 

pw_getcmsname(pw, name) 

Pixwin *pw; 

char name[CMS_NAMESIZE]; 


If you set the foreground and back¬ 
ground colors (which are entries 
count -1 and 0 in the colormap 
segment, respectively) to the same 
color, the system will change them 
to the foreground and background 
colors of sunview. In other words, 
you are prevented from making the 
foreground and background colors 
of a pixwin indistinguishable. 


Setting the name resets the colormap segment to a NULL entry. After calling 
pw_setcmsname (), you must immediately call pw_j?ut colormap () to set 
the size of the colormap segment and load it with the actual colors desired. 
pw_j?ut colormap () and the corresponding routine to retrieve the colormap’s 
state, pw_getcolormap (), are defined as follows: 
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Cycling the Colormap 


Miscellaneous Utilities 


pw_putcolormap(pw, index, 
Pixwin *pw; 

int index, 

unsigned char red[]. 


count, red, green, blue) 
count; 

green[], blue[]; 


pw_getcolormap(pw, index, count, red, green, blue) 

Pixwin *pw; 

int index, count; 

unsigned char red[ ], green[ ], blue[ ]; 

pw_put colormap loads the count elements of the pixwin’s colormap seg¬ 
ment starting at index (zero origin) with the first count values in the three 
arrays. 

The first time pw_put colormap () is called after calling 
pw_set cmsname (), the count parameter defines the size of the colormap 
segment. The size of a colormap segment must be a power of 2, and can’t be 
changed unless pw set cmsname () is called with another name. You can call 
pw_put colormap () subsequently to modify a subrange of the colormap — 
use a larger value for index and a smaller value for count. 

NOTE If you attempt to install a colormap segment that is not a power of 2, your color- 

map segment has a high likelyhood of taking up too much space. This means 
that the screen will flash when you move the cursor into the window with this 
odd sized colormap. 

In Appendix A, Example Programs, there is a program called coloredit which 
uses pw_putcolormap () to change the colors of its subwindows as the user 
adjusts sliders for red, green and blue. 


A utility is provided to make it easy to cycle colormap entries: 

pw_cyclecolormap(pw, cycles, index, count) 
Pixwin *pw; 

int cycles, index, count; 


Starting at index, the count entries of the colormap associated with the 
pixwin’s window are rotated among themselves for cycles. A cycle is defined 
as number of shifts it takes one entry to move through every position once. 

To see an example of colormap cycling, run jumpdemo (6) with the -c option. 

If you are are going to cycle one of the common colormap segment definitions, 
you should give the colormap a unique name, otherwise the colormap of other 
applications will change as well. 

The following utilities are provided as convenient ways to set the forground and 
background colors to common settings, min should be the first entry in the 
colormap segment, representing the background color, max should be the last 
entry, representing the forground color. 
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Using Color 


Cursors and Menus 


pw_reversevideo(pw, min, max) 
Pixwin *pw; 
int min, max; 


pw__blackonwhite (pw, min, max) 
Pixwin *pw; 
int min, max; 


pw_whiteonblack(pw, min, max) 
Pixwin *pw; 
int min, max; 


On a monochrome display, these calls don’t take effect until you write to the 
pixwin. On a color display, they take effect immediately. 


This section gives some notes on the use of color by cursors and menus, how to 
make color applications compatible with monochrome and grayscale screens, and 
how to use double buffering for smooth animation. 


Cursors appear in the foreground color, the last color in the pixwin’s colormap. 

Menus and prompts use fullscreen access, covered in Chapter 12, Menus and 
Prompts, of the SunView 1 System Programmer’s Guide. Fullscreen access saves 
the colors in the first and last entries of the screen’s colormap, puts in the fore¬ 
ground and background colors, and displays the menu or prompt. This means 
that depending on where your application’s colormap segment resides in the 
screen’s colormap, some colors in your tool may change whenever menus or 
prompts are put up. You can allow for this by making the background and fore¬ 
ground colors in your colormap segment the same as the screen’s background 
and foreground. 

There are other menu/cursor “glitches” that occur when running applications on 
frame buffers which support multiple plane groups. These are covered in the 
later section on Multiple Plane Groups. 


Is My Application Running on a None of the colormap manipulations described in this chapter causes an error if 
Color Display? run on a monochrome display. All colors other than zero map to the foreground 

color, so if your application displays colored objects on a background of zero, 
they will appear as black objects on a white foreground on a monochrome 
display 46 . The window system detects and prevents the foreground and back¬ 
ground being the same color on color displays. 

However, you may may want to determine at run time whether your application 
has a color or monochrome display available to it. For example, when displaying 
a chart, you may want to use patterns if colors are not available. You can deter¬ 
mine whether the display is color or monochrome by finding out how deep the 
pixels are. Each pixwin includes a pointer to a pixrect which represents its pixels 
on the screen. Pixrects, in turn, have a depth field which holds the number of bits 

44 Unless you are running with Mack and white inverted, using the -i option to sunview. 
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per screen pixel. Thus 


c - 

A 

Pixwin *pw; 


int depth = pw->pw_jpixrect->pr_depth; 


s._______ 

_> 


will have a value of 1 for windows displayed on monochrome devices, and a 
value greater than 1 for color screens. Currently, all Sun color displays have 8 
bits per pixel. 


Simulating Grayscale on a There is no way to tell if your application is running on a grayscale monitor. 

Color Display since it runs off the same color board. The grayscale monitor is usually driven 

from the red output of the color board, so if two colors have different green and 
blue values but the same red value, they will show up the same on a greyscale 
display. 

To see how your color application will look on a grayscale monitor, temporarily 
set your colormap segment so that the green and blue components of each color- 
map entry are the same as the red component. This will simulate the grayscale 
display on a color monitor. 

Software Double Buffering Sometimes you want to rapidly display different images in an application. If you 

just use the pixwin write operations to display the new image, the redrawing of 
the pixels will be perceptible to the user, even though the operations are fast. 
Instead, you can use a technique called software double-buffering. 

As we have seen, on a color display, there are 8 bits associated with each pixel. 

If you are not using 256 shades at once, then some of these bits are unused. 

What you would like to do is to store values for two or more different images in 
these 8 bits, but only display one set of values at a time. 

The first goal can easily be accomplished using the pw_j>utattributes () 
routine to restrict writes to a particular set of planes: 

pw_j?utattributes (pw, planes) 

Pixwin *pw; 
int *planes; 


planes is a bitplane access enable mask. Only those bits of the pixel 
corresponding to a 1 in the same bit position of *planes will be affected by 
pixwin operations. If planes is NULL, that attribute value will not be written. 

A corresponding routine is provided to retrieve the value of the access enable 
mask: 

pw_getattributes(pw, planes) 

Pixwin *pw; 
int *planes; 

NOTE Use pw_putattributes () with care, as it changes the internal state of the 
pixwin.~ The correct usage is to first save the existing bitplane mask by calling 
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pw_get at tributes (), then call pw_j>ut attributes (), then, when 
done, restore the initial state by calling pw_put at tributes () with the saved 
mask. 

The second goal — only displaying what is in some of the planes — is trickier. 
There is no way to tell the hardware to only look at the values in some of the 
planes to determine the colors to show. 

What you do instead is modify the colormap so that only values in certain planes 
of the colormap change the color on the display, so in effect only those planes are 
visible. For example, to display two different four-color images you could use 
the colormap shown in the following table. 

Table 7-1 Sample Colormap to Isolate Planes 


Pixel Value 

Colormap A 
(Only upper planes 
are “visible") 

Colormap B 
(Only lower planes 
are “visible” 

0 0 0 0 

blue 

blue 

0 0 0 1 

blue 

red 

0 0 10 

blue 

green 

0 0 11 

blue 

pink 

0 10 0 

red 

blue 

0 10 1 

red 

red 

0 110 

red 

green 

0 111 

red 

pink 

10 0 0 

green 

blue 

10 0 1 

green 

red 

10 10 

green 

green 

10 11 

green 

pink 

110 0 

pink 

blue 

110 1 

pink 

red 

1110 

pink 

green 

1111 

pink 

pink 


From the above table, you can see that if colormap A is set (using 
pw_put colormap () ), then no matter what the value in the two lower planes, 
the color displayed is the same; the value in the upper two planes alone controls 
the color. So, if you use this colormap while only enabling the two lower planes 
(by passing pw^put at tributes () the value 3 ), then the values you write 
into the lower planes won’t change what is shown. 

When you switch to colormap B, the situation is reversed. Only the values in the 
lower planes affect what is visible. You would then pass 
pw_putattributes () the value 12 to write to the upper two planes. The 
two sets of colors need not be the same, so you can switch between two 
different-colored images. 
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Using Software Double 
Buffering For Smooth 
Animation 


Hardware Double-Buffering 


You would use the same technique to switch between more images and/or to 
display more colors. You can display two different images, each with 16 dif¬ 
ferent colors, or 8 different monochrome images, or values in between. 

One application of the above technique is to provide smooth animation. To 
move an image across the screen, you must draw it in one location, erase it, and 
redraw it in another. Even on a fast system, the erasing and redrawing is visible. 
You’d like the object to immediately appear in its new position, without disap¬ 
pearing momentarily. You can do this by alternating two colormaps so that the 
object disappears in its old location and reappears in a new one. This is called 
software double-buffering, because you are using the display planes as alternat¬ 
ing buffers; as you write to one set of planes, the other set of planes is displayed. 

The colormaps in the table on the preceding page come from the software pro¬ 
gram animatecolor in Appendix A, Example Programs. This program uses 
software double buffering to animate some squares. The routines it uses to create 
the two colormaps and swap between them are complicated, but can be reused in 
more sophisticated graphics applications. 

The following routines will allow programs to do true hardware double-buffering 
on the Thecg5board. on the device driver interface, refer the the cgtwo(4S) 
manual page. 47 color framebuffer and on future framebuffers that support 
double-buffering. 

Double-buffering is treated as an even scarcer resource than colormaps, since 
only one window can be truly double-buffered at any one time. The cursor con¬ 
trols which window will flip the display buffers. Applications are able to run the 
same code on non-double-buffered displays and it will be as if the double¬ 
buffering calls were never made. The following code fragment contains proto¬ 
typical application code. 

-- 

Rect rectangle; 

Pixwin *pw; 
rectangle.r_left= ... ; 

if (!pw_dbl_get (pw, PW_DBL_AVAIL)) 

{ ... if program cares ... } 
pw_dbl_access (pw); * 

while (rendering__frames) { 

... calculate one frame ... 
pw_lock (pw, &rectangle); 

... render one frame ... 

... may include unlocks and locks ... 
pw__dbl_flip (pw); 
pw_unlock (pw); 

} 

pw_dbl_release (pw); 

s___ ) 


47 The cg5 board is binary compilable with both the Sun-3 Color Board and the Sun-2 Color Board. cg5 is 
necessary for hardware double-buffering. 
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The notion of the “active” double-buffering window is important. There is at 
most one active window at a time. If the cursor is in a double-buffering window, 
then the window is the active double-buffering window. If the cursor leaves the 
active window, that window remains active until the cursor enters another 
double-buffering window. If the active double-buffering window dies, goes 
iconic, or becomes totally obscured, and the cursor is not left in a double¬ 
buffering window, then the top-most visible double-buffering window becomes 
the active window (if there is one). 

Only the active window will be allowed to write to a single buffer. All other win¬ 
dows write to both buffers, so that when the display flips to the other buffer, their 
contents remain unchanged. The notion of active will change only during a 
pw_dbl_f lip () call. 

pw_dbl_access() which resets the window’s data structure so that first frame 
will be rendered to the background. The very first double buffer sets both READ 
and WRITE to the backgound. pw_dbl_access() should only be called when 
ready to actively animate: 

pw_dbl_access (pw) 

Pixwin *pw; 

If the pixwin’s window has not been accessed for double-buffering then there is 
no change, and both buffers will be written to. 

If the window is marked as accessible for double-buffering and the window is 
“active”, then the frame double-buffering control to whatever this window 
requested with its last pw_dbl_set () call. If there was no pw_dbl_set () 
call, then set write and READ to the background. Change the frame buffer 
double-buffering control bits to reflect this. 

If the window is accessible for double-buffering then potentially flip the display. 
The display is flipped only if the window is “active” : pw_dbl_f lip () deter¬ 
mines if its window has become active: 

pw_dbl_flip(pw) 

Pixwin *pw; 

The flip can be done inside or outside of a lock region although it may be prefer¬ 
able to place inside a lock region just before an unlock so that calculations for the 
next frame can proceed even if another window momentarily grabs the lock. The 
flip from one buffer to another is synchronized with the display’s vertical retrace. 

The procedure 

pw_dbl_release(pw) 

Pixwin *pw; 

signifies the end of double-buffering by the window associated with the pixwin. 
Call pw_dbl_release () as soon as your program has completed a section of 
active animation. This procedure will copy the foreground buffer to the back¬ 
ground. Because of this, it is important to leave the animation loop after a 
pw_dbl_f lip () has been done and before drawing the next frame has started. 
Otherwise, the window will contain an incomplete buffer image after the release. 
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SunView provides the ability for an actively double-buffering window to write to 
both buffers. For example, the instrument gauge readings can be set in a real¬ 
time simulator. If pw is not the active double buffer, the frame buffer control bits 
are not changed. The procedure and the attributes that it may use are discussed 
below. 

pw_dbl_set(pw, attributes) 

Pixwin *pw; 

<attribute-Iist> attributes; 


Table 7-2 Pixwin-Level set Attributes 


Attribute 


Possible Values to set 


PW_DBL_WRITE 
PW DBL READ 


PW_DBL_FORE, PW_DBL_BACK, PW_DBL_BOTH 
PW DBL FORE, PW_DBL_BACK_ 


The attribute value returned from pw_dbl_get () does not reflect the true state 
of double buffering hardware. This is especially true if the active double buffer 
is not this pixwin. The procedure and the attributes that is uses are given below. 


pw_dbl_get(pw, attribute) 

Pixwin *pw; 

Pw dbl attribute attribute; 


Table 7-3 Pixwin-Level get Attributes 


Attribute 

Possible Values Returned 

PW_DBL_AVAIL 

PW_DBL_DISP LAY 

PW_DBL_EXISTS 

PW_DBL_WRITE 

PW_DBL_FORE, PW_DBL_BACK, PW_DBL_BOTH 

PW DBL READ 

PW DBL FORE, PW DBL BACK 


7.6. Plane Groups and the 
cgfour Frame Buffer 


The Sun-3/110, Sun-3/60, and Sun-4/110 color machines use the 
cgfour (4s) 48 frame buffer, which supports multiple “plane groups.” Each 
displays either 24-bit color or black and white. In the former case its color is 
determined by a value in an 8-bit color buffer, in the latter case, a monochrome 
buffer called the overlay plane. 

Whether the pixel displays in color or black/white is controlled by the value for 
the pixel in the enable plane, a third plane. If the value in the enable plane is not 
set, then the 8-bit deep value in the color buffer is passed to the circuitry that pro¬ 
duces the color from the lookup table. If it is set, then the overlay plane deter¬ 
mines the pixel’s color (black or white). The effect is like having a color and 
monochrome display in one, with the enable plane determining which is shown 
in each pixel. 


48 Read the cgfour (4s) manual page for more information on this frame buffer architecture. 
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In fact, in the color Sun-3/60 and Sun-4/110 plane group implementations, you 
can set the colors in the overlay plane to other that black and white. There are 
only two colors in the overlay plane since it is only one-bit deep, but they can 
have colors other than black and white assigned to them. 

Such sets of buffers are referred to as plane groups. 

SunView and Plane Groups At the pixrect level it is possible to manipulate the three plane groups of multiple 

plane group framebuffers directly. At the SunView level, some decisions have 
been made for you. Raster operations in the overlay plane are faster than in the 
color plane, so SunView objects which only use the foreground and background 
colors such as frames, text subwindows, panels, cursors, menus, etc. all try to ran 
in the overlay plane. If you set the foreground and background explicitly using 
the techniques explained in Changing Colors from the Command Line above, or 
if you have told sunview to run in the color buffer only by giving it the com¬ 
mand line argument -8bit_color_only, then these objects will run in the 
color plane. 

However, canvases and graphics subwindows default to using the color plane 
group whenever possible, on the assumption that you want to draw in color. If 
this is not the case, then you may find that your application runs faster if you hint 
to these subwindows to use the overlay plane: 

□ For canvases, set the attribute CANVAS_FAST_MONO, either when creating 
the canvas or later, as in: 


window_set(canvas, CANVAS_FAST_MONO, TRUE, 0) ; 


If your application uses scrollbars, then you need to set 
CANVAS_FAST_MONO before you create the canvas’ scrollbars, since they 
share the canvas’ pixwin. 

□ For graphics subwindows in old-style Sun Windows applications, use the 
pixwin call pw_use_f ast_monochrome (pw) as follows: 

' ----- \ 

pw_use_fast_monochrome (gfx->gfx_jpixwin) ; 

---, 


Both calls affect only multiple plane group displays, so it is safe and desirable to 
put them in any Sun application that uses monochrome canvases or graphics 
subwindows. Again, if the user gives the appropriate command line arguments, 
canvases and graphics subwindows will ran in the color plane regardless of these 
calls. 



microsystems 


Revision A, of May 9, 1988 









126 SunView 1 Programmer’s Guide 


“Glitches” Visible when Using 
Plane Groups 


sunview and Plane Groups 


For performance reasons, the cursor image is only written in the plane group of 
the window under it. So, if the cursor’s hot spot is in a black and white window 
in the overlay plane and there is an adjacent color window, that part of its image 
that would lie over the color window is invisible, since it is drawn in the overlay 
plane but the enable plane is still showing the value in the color buffer. The 
same disappearance applies in the reverse situation. 

When menus are drawn, the enable plane is set so that they are visible. 

It is possible to direct sunview(l) to only use the color buffer or the overlay 
plane; it is also possible to start up a second copy of sunview in the other plane 
group, and switch between them using swit cher(l) or - 
ad jacent screens(l). Consult these programs’ manual pages for more infor¬ 
mation. 
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Summary Tables 



Text Sub windows 


This chapter describes the text subwindow package, which you can use by 
including the file <suntool/textsw. h>. 

Figure 8-1 is a text subwindow. A text subwindow allows a user or client to 
display and edit a sequence of ASCII characters. These characters are stored in a 
file or in primary memory. Its features range from inserting into a file to search¬ 
ing for and replacing a string of text or a character. 

Figure 8-1 Text Subwindow 


textedit - (NONE), dir: /usr/topaz/yvonne 



To give you a feeling for what you can do with text subwindows, overleaf there 
is a list of the available text subwindow attributes and functions. Many of these 
are discussed in the rest of this chapter and elsewhere (use the Index to check). 
All are briefly described with their arguments in the text subwindow summary 
tables in Chapter 19, SunView Interface Summary: 

□ the Text Subwindow Attributes table begins on page 366; 

□ the Text sw_act ion Attributes table begins on page 370; 

□ the Textsw_status Values table begins on page 371; 

□ the Text Subwindow Functions table begins on page 372. 
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Text Subwindow Attributes 


TEXTSW ADJUST IS PENDING DELETE 

TEXTSW_INSERT_FROM_FILE 

TEXTSW AGAIN_RECORDING 

TEXTSW_INSERT_MAKES_VISIBLE 

TEXTSW AUTO INDENT 

TEXTSW_INSERTION_POINT 

TEXTSW_AUTO_SCROLL_BY 

TEXTSW_LEFT_MARGIN 

TEXTSW BLINK_CARET 

TEXTSW_LENGTH 

TEXTSW_BROWSING 

TEXTSW_LINE_BREAK_ACTION 

TEXTSW_CHECKPOINT_FREQUENCY 

TEXTSW_LOWER_CONTEXT 

TEXT SW_CLIENT_DATA 

TEXT SW_MEMORY_MAXIMUM 

TEXT SW_CONFIRM_OVERWRITE 

TEXTSW_MENU 

TEXTSW_CONTENTS 

TEXTSW_MODIFIED 

TEXT SW_CONTROL_CHARS_U SE_F ONT 

TEXTSW_MULTI_CLICK_SPACE 

TEXT SW_DISABLE_CD 

TEXTSW_MULTI_CLICK_TIMEOUT 

TEXTSW_DISABLE_LOAD 

TEXTSW_NOTIFY_PROC 

TEXTSW_EDIT_COUNT 

TEXT SW_READ_ONLY 

TEXTSW_FILE 

TEXTSW_SCROLLBAR 

TEXTSW_FILE_CONTENTS 

TEXTSW_STATUS 

TEXTSW_FIRST 

TEXTSW_STORE_CHANGES_FILE 

TEXTSW_FIRST_LINE 

TEXTSW_STORE_SELF_IS_SAVE 

TEXTSW_HISTORY_LIMIT 

TEXTSW_UPDATE_SCROLLBAR 

TEXTSW_IGNORE_LIMIT 

TEXTSW_UPPER_CONTEXT 


Textsw 

action Attributes 

TEXT SW_ACTION_CAPS_LOCK 

TEXTSW_ACTION_TOOL_CLOSE 

TEXT SW_ACTION_CHANGED_DIRECTORY 

TEXTSW_ACTION_TOOL_DESTROY 

TEXT SW_ACTION_EDITED_FILE 

TEXT SW_ACTION_TOOL_QUIT 

TEXTSW_ACTION_EDITED_MEMORY 

TEXTSW_ACTION_TOOL_MGR 

TEXT SW_ACTION_FILE_IS_READONLY 

TEXTSW_ACTION_USING_MEMORY 

TEXTSW_ACTION_LOADED_FILE 
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8.1. Text Subwindow 
Concepts 

Creating a Subwindow 


Attribute Order 


Determining a Character’s 
Position 


Getting a Text Selection 


Editing a Text Subwindow 


This section introduces the basic concepts of a text subwindow. 

You create a text subwindow the same way that you create any SunView window 
object, by calling the window creation routine with the appropriate type parame¬ 
ter: 


Textsw textsw; 

textsw = window create (base_frame, TEXTSW, attributes, 0) , 


The attributes in the above call constitute an attribute list which is discussed in a 
Section later in this chapter, titled Attribute-based Functions. 


Most attributes are orthogonal; thus you usually need not worry about their order. 
However, in a few cases the attributes in a list may interact, so you need to be 
careful to specify them in a particular order. Such cases are noted in the sections 
which follow. 49 In particular, you must pass TEXTSW_STATUS first in any call 
to window_create () or window_set () if you want to find the status after 
setting some other attribute in the same call. 

The contents of a text subwindow are a sequence of characters. At any moment, 
each character can be uniquely identified by its position in the sequence (type 
Textsw_index). Editing operations, such as inserting and deleting text, cause 
the index of any particular character to change over time. The valid indices are 0 
through length-1 inclusive, where length is the number of characters currently in 
the text subwindow, returned by the TEXTSW_LENGTH attribute. 

The text subwindow has a notion of the current index after which the next char¬ 
acter will be inserted at any given moment. This is called the insertion point. A 
caret is drawn on the screen immediately after this index to give the user a visual 
indication of the insertion point. 

A text selection is made by the user, and it is indicated on the screen with 
reverse-video highlighting. A text subwindow function or procedure is not used 
to determine which window has the current selection or to retrieve information 
contained in a text subwindow. Instead, these functions are earned out by the 
Selection Service. For an example of how this is done, refer to Section 16, The 
Selection Service. 

A text subwindow may be edited by the user, or by a client program. When you 
create a text subwindow, by default the user can edit it. By using the special 
attributes discussed in this section, the client program can edit the subwindow. 
These edits are then stored in /tmp/textProcess-id.Counter. 

The following five sections explain the functions and attributes that you will use 
to load, read, write, edit, and finally save a text file. 

49 For a discussion of attribute ordering in general, see Section 4.8, Attribute Ordering. 
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8.2. Loading a File 


You can load a file into a textsw by using TEXTSW FILE, as in: 
f “ > 
window_set (textsw, TEXTSW_FILE, file__name, 0) ; 
v-—___> 


Keep in mind, that if the existing text has been edited, then these edits will be 
lost. To avoid such loss, first check whether there are any outstanding edits by 
calling: 

- -- .. 

window_get(textsw, TEXTSW_MODIFIED) 
---, 


The above call to window_set () will load the new file with the text posi¬ 
tioned so that the first character displayed has the same index as the first charac¬ 
ter that was displayed in the previous file — which is probably not what you 
want. To load the file with the first displayed character having its index specified 
by position, use the following: 

- — ->. 

window_set(textsw, TEXTSW_FILE, file_name, 

TEXTSW_FIRST, position, 0); 

___y 


NOTE The order of these attributes is important. Because attributes are evaluated in 
the order given, reversing the order would first reposition the existing file, then 
load the new file. This would cause an unnecessary repaint, and mis-position the 
old file, if it was shorter than posit ion. For a full discussion of attribute ord¬ 
ering, see Section 8.5. 

Checking the Status of the Both of the above calls blindly trust that the load of the new file was successful. 

Text Subwindow This is, in general, a bad idea. To find out whether the load succeeded, and if 

not, why not, use the following call: 

- 

window_set(textsw, 

TEXTSW_STATUS, Sstatus, 

TEXTSW_FILE, file_name, 

TEXTSW_FIRST, position, 

0 ) ; 

k_/ 

where status is declared to be of type Textsw_status. 

NOTE The TEXTSW_STATUS attribute and handle must appear in the attribute list 
before the operation whose status you want to determine. 

Text sw_status Value The valid values for such a variable are enumerated in the following table, where 

the common prefix TEXTSW_STATUS_ has been removed. For example, OKAY 
in the table is actually TEXTSW_STATUS_OKAY. 
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Table 8-1 Textsw_status Values 

Value _ Description _ 

The operation encountered no problems. 

The attribute list contained an illegal or unrecognized attribute. 


TEXT SW_S TATU S_OKAY 

TEXT SW_S TATU S_BAD_AT TR 

TEXT SW_S TATU S_BAD_AT TR_VALUE 

TEXTSW_STATUS_CANNOT_ALLOCATE 

TEXT S W_S TATU S_C ANN OT__OP EN_I NP UT 

TEXT S W_S TAT U S_C ANN OT_I N SERT_FROM__F ILE 

TEXTSW_STATUSJ3UT_0F_MEM0RY 
TEXTSW STATUS OTHER ERROR 


The attribute list contained an illegal value for an attribute, 
usually an out of range value for an enumeration. 

A call to calloc(2) or malloc(2) failed. 

The specified input file does not exist or cannot be accessed. 

The operation encountered a problem when trying 
to insert from file. 

The operation ran out of memory while editing in memory. 

The operation encountered a problem not covered by any of 
the other error indications. 


8.3. Writing to a Text 
Subwindow 


To insert text into a text subwindow at the current insertion point, call: 

Textsw_index 

textsw_insert(textsw, buf, buf_len) 

Textsw textsw; 
char *buf; 
int buf_len; 

The return value is the number of characters actually inserted into the text 
subwindow. This number will equal buf_len unless either the text subwindow 
has had a memory allocation failure, or the portion of text containing the inser¬ 
tion point is read only. The insertion point is moved forward by the number of 
characters inserted. 


NOTE This routine does not do terminal-style interpretation of the input characters. 

Thus “editing” characters (such as CTRL-H or DEL for character erase, etc.) are 
simply inserted into the text subwindow rather than performing edits to the exist¬ 
ing contents of the text subwindow. In order to do terminal-style emulation, you 
must pre-scan the characters to be inserted, and invoke textsw_edit () where 
appropriate, as described in the next section. 
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Insertion Point The attribute TEXTSW_INSERTI0N_P0INT is used to interrogate and to set 

the insertion point. For instance, the following call determines where the inser- 


tion point is: 

Textsw_index point; 

point = (Textsw_index)window_get(textsw, 

TEXTSW_INSERTION_POINT) ; 

L-_ 

_ 

A 

whereas the following call sets the insertion point to be just before the third char¬ 
acter of the text: 

window_set (textsw, TEXTSW_INSERTION_POINT, 2, 0); 

<_ 

\ 


Positioning to End of Text To set the insertion point at the end of the text, set 

textsw_insertion_point to the special index TEXTSW__INFINITY. 

NOTE This call does not ensure that the new insertion point will be visible in the text 
subwindow, even if the TEXTSW_INSERT_MAKES_VISIBLE attribute is 
TRUE. To guarantee that the caret will be visible afterwards, you should call 
textsw_j?ossibly_normalize (). 

8.4. Reading from a Text Many applications that incorporate text subwindows never need to read the con- 
Subwindow tents of the text directly from the text subwindow. Often, this is because the text 

subwindow is only being used to display text to the user. 

Even when the user is allowed to edit the text, some applications simply wait for 
the user to perform some action that indicates that all of the edits have been 
made. They then use either textsw_save () or textsw_store_f ile () to 
place the text in the file. The text can then be read via the usual file input utili¬ 
ties, or the file itself can be passed off to another program. 

It is, however, useful to be able to directly examine the text in the text subwin¬ 
dow. You can do this using the TEXTSW_CONTENTS attribute. The following 
code fragment illustrates how to use TEXTSW_CONTENTS to get a span of char¬ 
acters from the text subwindow. It gets the 1000 characters beginning at position 
500 out of the text subwindow and places them into a null-terminated string. 

f -—--N 

♦define TO_READ 1000 

char buf[TO_READ+l]; 

Textsw_index next_pos; 

next_j?os = (Textsw_index) 

window_get(textsw, TEXTSW_CONTENTS, 500, buf, TO_READ) ; 

if (next_jpos != 500+TO_READ) { 

Error case 
} else 

buf[TO_READ] = '\0'; 

v___> 
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8.5. Editing the Contents of The file or memory being edited by a text subwindow is referred to as the back- 
a Text Subwindow ing store. Several attributes and functions are provided to allow you to manipu¬ 

late the backing store of a text subwindow. 50 This section describes the pro¬ 
cedures and attributes that you can use to edit a text subwindow. 


Removing Characters You can remove a contiguous span of characters from a text subwindow by cal¬ 

ling: 

Textsw_index 

textsw__delete (textsw, first, last_j?lus_one) 

Textsw textsw; 

Textsw_index first, last_plus_one; 

first specifies the first character of the span that will be deleted, while 
last_plus_one specifies the first character after the span that will not be 
deleted, first should be less than, or equal to, last_plus_one. To delete 
to the end of the text, pass the special value TEXTSW_INFINITY for 
last_j?lus_one. 

The return value is the number of characters deleted, and is last_plus_one 
- first, unless all or part of the specified span is read-only. In this case, only 
those characters that are not read-only will be deleted, and the return value will 
indicate how many such characters there were. If the insertion point is in the 
span being deleted, it will be left at first. 

A side-effect of calling textsw_delete () is that the deleted characters 
become the contents of the global Clipboard. To remove the characters from the 
textsw subwindow without affecting the Clipboard, call: 

Textsw_index 

textsw_erase(textsw, first, last_plus_one) 

Textsw textsw; 

Textsw_index first, last_j?lus_one; 

Again, the return value is the number of characters removed, and 
last_plus_one can be TEXTSW_INFINITY. 

Both of these procedures will return 0 if the operation fails. 

Emulating an Editing You can emulate the behavior of an editing character, such as CTRL-H, with 

Character textsw_edit (): 

Text s w__index 

textsw_edit(textsw, unit, count, direction) 

Textsw textsw; 

unsigned unit, count, direction; 


50 Note that the edit log maintained by the text subwindow package is reset on each operation affecting the 
backing store. For a description of the edit log, see the discussion at the end of Editing the Contents of a Text 
Subwindow. 
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Replacing Characters 


Depending on the value of unit, this routine will erase either a character, a 
word, or a line. Set unit to: 

□ TEXTSW_UNIT_IS_CHAR to erase individual characters, 

□ TEXTSW_UNIT_IS_W0RD to erase the span of characters that make up a 
word (including any intervening white space or other non-word characters), 
or 

□ textsw_unit_is_line to erase all characters in the line on one side of 
the insertion point. 

If the direction parameter is 0, the operation will affect characters after the 
insertion point, otherwise it will affect characters before the insertion point 

The number of times the operation will be applied is determined by the value of 
the count parameter. Set it to one to do the edit once, or to a value greater than 
one to do multiple edits in a single call. textsw_edit () returns the number 
of characters actually removed. 

For example, suppose you want to interpret the function key ITT) as meaning 
“delete word forward”. On receiving the event code for the (FT) key going up, 
you would make the call: 

--- \ 

textsw_edit(textsw, TEXTSW_UNIT_IS_WORD, 1, 0); 

- ---- , 


While a span of characters may be replaced by calling text sw_erase () fol¬ 
lowed by textsw_insert ( ), character replacement is done most efficiently 
by calling: 

Text sw_index 

textsw_replace_bytes(textsw, first, last_plus_one, buf, buf_len) 
Textsw textsw; 

Textsw_index first, last_plus_one; 
char *buf; 

int buf_len; 

The span of characters to be replaced is specified by first and 
last_jplus_one, just as in the call to text sw_erase (). The new charac¬ 
ters are specified by buf and buf_len, just as in the call to 
textsw_insert (). Once again, if last_plus_one is 
TEXTSw_infinity, the replace affects all characters from first to the end 
of the text. If the insertion point is in the span being replaced, it will be left at 
first + buf_len. 

The return value is the net number of bytes inserted. The number is negative if 
the original string is longer than the one which replaces it. If a problem occurs 
when an attempt is made to replace a span, then it will return an error code of 0. 

textsw_replace_bytes (), like text sw_erase () , does not put the 
characters it removes on the global Clipboard. 
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The Editing Log All text subwindows allow the user to undo editing actions. In order to imple¬ 

ment this feature, the text subwindow package keeps a running log of all the 
edits. If there is a file associated with the text subwindow, this log is kept in a 
file in the /tmp directory. 

This file can grow until this directory runs out of space. To limit the size of the 
edit log and to avoid filling up all of tmp the user can set the tex wrap around 
size in the default sedit(l) Tty/text_wraparound_size . If there is no associ¬ 
ated file, the edit log is kept in memory, and the maximum size of the log is con¬ 
trolled by the attribute TEXTSW_MEMORY_MAXIMUM, which defaults to 20,000 
bytes. 

Unfortunately, once an edit log kept in memory has reached its maximum size, 
no more characters can be inserted into or removed from the text subwindow. In 
particular, since deletions, as well as insertions, are logged, space cannot be 
recovered by deleting characters. 

It is important to understand how the edit log works because you may want to use 
a text subwindow with no associated file to implement a temporary scratch area 
or error message log. If such a text subwindow is used for a long time, the 
default limit of 20,000 bytes may well be reached, and it will be impossible for 
either the user or your code to insert any more characters even though there may 
be only a few characters visible in the text subwindow. Therefore, it is recom¬ 
mended to set TEXT SW_MEMORY_MAX IMUM much higher, say to 200,000. 

Which File is Being Edited? To find out which file the text subwindow is editing, call: 

int 

textsw_append_f ile__name (textsw, name) 

Textsw textsw; 
char *name; 

If the text subwindow is editing memory, then this routine will return a non-zero 
value. Otherwise, it will return 0, and append the name of the file to the end of 
name. 

If a text subwindow is editing a file called my file and the user chooses ‘Save 
Current File’ from the subwindow’s menu (or client code invokes 
textsw_save ()), the following sequence of file operations occurs: 

a myfile is copied to myfile% 

□ The contents of my f i 1 e % are combined with information from the edit log 
file (/tmp /Text Process-id. Counter) and written over myfile (thereby 
preserving all its permissions, etc). 

□ The edit log file is removed from /tmp. 

If myfile is a symbolic link to .Jsome_dir/ otherf ile, then the backup file 
is created as ../some dir/ otherf ile%. 


Interactions with the File 
System 
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8.6. Saving Edits in a 
Subwindow 


Storing Edits 


Discarding Edits 


Keep in mind that the user can change the current directory by selecting ‘Load 
File’ or ‘Set Directory’ from the text subwindow menu. If my file is a relative 
path name, then the copy to myf ile% and the save take place in the current 
directory. 

To save any edits made to a file currently loaded into a text subwindow call: 
unsigned 

textsw_save(textsw, locx, locy) 

Textsw textsw; 
int locx, locy; 

locx and locy are relative to the upper left comer of the text subwindow and 
are used to position the upper left comer of the alert should the save fail for some 
reason — usually they should be 0. The return value is 0 if and only if the save 
succeeded. 

The text subwindow may not contain a file, or the client may wish to place the 
edited version of the text (whether or not the original text came from a file) in 
some specific file. To store the contents of a text subwindow to a file call: 

unsigned 

textsw_store_file(textsw, filename, locx, locy) 

Textsw textsw; 
char *filename; 
int locx, locy; 

Again, locx and locy are used to position the upper left comer of the message 
box. The return value is 0 if and only if the store succeeded. 

NOTE By default, this call changes the file that the text subwindow is editing, so that 
subsequent saves will save the edits to the new file. To override this policy, set 
the attribute TEXTSW_STORE_CHANGES_FILE to FALSE. 

To discard the edits performed on the contents of a text subwindow, call: 
void 

textsw_reset(textsw, locx, locy) 

Textsw textsw; 
int locx, locy; 

locx and locy are as above. Note that if the text subwindow contains a file 
which has not been edited, the effect of textsw reset is to unload the file 
and replace it by memory provided by the text subwindow package; thus the user 
will see an absolutely empty text subwindow. Alternatively, if the text subwin¬ 
dow already was editing memory then another, untouched, piece of primary 
memory will be provided and the edited piece will be deallocated. 

The rest of this chapter describes the other functions that are available for text 
subwindows. These features include setting the contents of a subwindow, setting 
the primary selection, and how to deal with multiple or split views. 
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8.7. Setting the Contents of You may want to set the initial contents of a text subwindow that your applica- 

a Text Subwindow tion uses. For example, the SunView mailtool sets the initial contents of the 

composition window to come up with the headings To, Subject, and so on. 

To set the initial contents of a text subwindow, use one of three attributes: 
TEXTSW_INSERT_FROM_FILE, TEXTSW_FILE_CONTENTS, and 
TEXTSW__CONTENTS. Each attribute is illustrated in code fragments given 
below. 

TEXTSW_FILE_CONTENTS The attribute TEXTSW_FILE_C0NTENTS makes it possible for a client to ini¬ 
tialize the text subwindow contents from a file yet still edit the contents in 
memory. The user can return a text subwindow to its initial state after an editing 
session by choosing ‘Undo All Edits’ in the text menu. 

The following code fragment shows how you would use this attribute. 

Textsw textsw; 

char *filename; 

Textsw_index pos; 

window_set(textsw, 

TEXTSW_FILE_CONTENTS, filename, 

TEXTSW_FIRST, pos, 

0 ); 


When the client calls the undo routine and filename is not a null string, then it 
will initialize the memory used by the text subwindow with the contents of the 
file specified by filename. 

When the client calls the undo routine and the filename is a null string, then it 
will initialize the memory used by the text subwindow with the previous contents 
of the text subwindow. 

TEXTSW CONTENTS TEXTSW_CONTENTS lets you insert a text string from memory, instead of a file, 

into the text subwindow. The default for this attribute is NULL. 

If you use window_create () with this attribute, then it will specify the initial 
contents for a non-file text subwindow. 

If you use window_set () with this attribute it will set the contents of a win¬ 
dow as in: 



If you use window_get () with this attribute, then you will need to provide 
additional parameters as in: 



The return value is the next position to be read. The buffer array 
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buf [0.. .buf_len-l ] is filled with the characters from textsw beginning at 
the index pos, and is null-terminated only if there were too few characters to fill 
the buffer. 

TEXTSW_lNSERT_FROM_FiLE textsw_insert_FROM_file allows a client to insert the contents of a file 

into a text subwindow at the current insertion point. It is the progr amm ing 
equivalent of a user choosing ‘Include File’ from the text menu. 

The following code fragment is a sample of using this attribute. 




8.8. Positioning the Text 
Displayed in a Text 
Subwindow 


Screen Lines and File Lines 



Three status values may be returned for this attribute when the argument 
TEXTSW_STATUS is passed in the same call to window_create () or 
window_set (): 

□ TEXTSW_STATUS_OKAY — the operation was successful. 

□ TEXTSW_STATUS_CANNOT_INSERT_FROM_FILE — the operation 
failed 

□ TEXTSW_STATUS_OUT_OF_MEMORY —the function cannot insert the 
text, because it ran out of memory 

Usually there is more text managed by the text subwindow than can be displayed 
all at once. As a result, it is often necessary to determine the indices of the char¬ 
acters that are being displayed, and to control exactly which portion of the text is 
being displayed. 

When there are long lines in the text it is necessary to draw a distinction between 
two different definitions of “line of text.” 

A screen line reflects what is actually displayed on the screen. A line begins 
with the leftmost character in the subwindow and continues across until either a 
newline character or the right edge of the subwindow is encountered. A file line, 
on the other hand, can only be terminated by the newline character. It is defined 
as the span of characters starting after a newline character (or the beginning of 
the file) running through the next newline character (or the end of the file). 

Whenever the right edge of the subwindow is encountered before the newline, if 
TEXTSW_LINE_BREAK_ACTION is TEXTSW_WRAP_AT_CHAR, the next 
character and its successors will be displayed on the next lower screen line. In 
this case there would be two screen lines, but only one file line. From the per¬ 
spective of the display there are two lines; from the perspective of the file only 
one. If, on the other hand TEXTSW_LINE_BREAK_ACTI0N is 
TEXTS W_WRAP_AT_W0RD, the entire word will be displayed on the next line. 
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Absolute Positioning 


Relative Positioning 


Unless otherwise specified, all text subwindow attributes and procedures use the 
file line definition. 

NOTE Line indices have a zero-origin, like the character indices; that is, the first line 
has index 0, not 1. 

Two attributes are provided to allow you to specify which portion of the text is 
displayed in the text subwindow. 

Setting the attribute TEXTSW_FIRST to a given index causes the first character 
of the line containing the index to become the first character displayed in the text 
subwindow. Thus the following call causes the text to be positioned so that the 
first displayed character is the first character of the line which contains index 
1000. This call only positions one view at a time: 


-- 

window_set(textsw, TEXTSW_FIRST, 1000, 0); 

L _____ 

\ 

To position all of the views in a text subwindow, use the attribute 

TEXTSW FOR ALL VIEWS as in the following call: 

— 

window_set(textsw,TEXTSW_FOR_ALL_VIEWS, TRUE, 

TEXTSW_FIRST, 1000, 0); 


Conversely, the following call retrieves the index of the first displayed character: 

c 

index * (Textsw index)window_get(textsw, TEXTSW_FIRST); 

v---—- 



A related attribute, useful in similar situations, is TEXTSW_FIRST_LINE. 
When used in a call on window_set () or window_get (), the value is a 
file line index within the text. 

You can determine the character index that corresponds to a given line index 
(both zero-origin) within the text by calling: 

Textsw_index 

textsw_index_for_file_line(textsw, line) 

Textsw textsw; 
int line; 

The return value is the character index for the first character in the line, so char¬ 
acter index 0 always corresponds to line index 0. 

To move the text in a text subwindow up or down by a small number of lines, 
call the routine: 

void 

textsw_scroll_lines(textsw, count) 

Textsw textsw; 
int count; 

A positive value for count causes the text to scroll up, just as if the user had 
used the left mouse button in the scrollbar, while a negative value causes the text 
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to scroll down, as if the user had used the right mouse button in the scrollbar. 

How Many Screen Lines are When calling text sw_scroll_lines () you may want to know how many 

in the Subwindow? screen lines are in the text subwindow. You can find this out by calling: 

int 

textsw_screen_line_count(textsw) 

Textsw textsw; 


Which File Lines are Visible? Exactly which file lines are visible on the screen is determined by calling: 

void 

textsw_file_lines_visible(textsw, top, bottom) 

Textsw textsw; 
int *top, *bottom; 

This routine fills in the addressed integers with the file line indices of the first and 
last file lines being displayed in the specified text subwindow. 

Guaranteeing What is Visible To ensure that a particular line or character is visible, call: 

void 

textsw_j?ossibly_normalize(textsw, position) 

Textsw textsw; 

Textsw_index position; 

The text subwindow must be displayed on the screen, before this function will 
work. 

If the character at the specified position is already visible, then this routine 
does nothing. If it is not visible, then it repositions the text so that it is visible 
and at the top of the subwindow. 

If a particular character should always be at the top of the subwindow, then cal¬ 
ling the following routine is more appropriate: 

void 

textsw_normalize_view(textsw, position) 

Textsw textsw; 

Textsw_index position; 


Ensuring that the Insertion Point 
is Visible 


Most of the programmatic editing actions do not update the text subwindow to 
display the caret, even if textsw_insert_makes_visible is set If you 
want to ensure that the insertion point is visible, call something like 

-——-- 

textsw_possibly_normalize(textsw, 

(Textsw_index) window_get(textsw, TEXTSW_INSERTION_POINT) ; 

V___, 
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8.9. Finding and Matching A common operation performed on text is finding a span of characters that match 
a Pattern some specification. The text subwindow provides several rudimentary pattern 

matching facilities. This section describes two functions that you may call in 
order to perform similar operations. 

To find the nearest span of characters that match a pattern, call: 
int 

textsw_find_bytes(textsw, first, last_plus_one, buf, 
buf_len, flags) 

Textsw textsw; 

Textsw_index *first, *last_plus_one; 
char *buf; 

unsigned buf_len; 

unsigned flags; 

The pattern to match is specified by buf and buf_len. The matcher looks for 
an exact and literal match — it is sensitive to case, and does not recognize any 
kind of meta-character in the pattern, first specifies the position at which to 
start the search. If flags is 0, the search proceeds forwards through the text, if 
1 the search proceeds backwards. The return value is -1 if the pattern cannot be 
found, else it is some non-negative value, in which case the indices addressed by 
first and last_plus_one will have been updated to indicate the span of 
characters that match the pattern. 

Matching a Specific Pattern Another useful operation is to find delimited text. For example, you might want 

to find the starting brace and the ending brace in a piece of code. To find a 
matching pattern, call: 

int 

textsw__match_bytes(textsw, first, last_plus_one, 

start_sym, start__sym_len, 
end_sym, end_sym_len, field_flag) 

Textsw 

Textsw_index 
char 
int 

unsigned 

first stores the starting position of the pattern that you want to search for. 
last_plus_one stores the cursor position of the end pattern. Its value is one 
position past the text. start_sym and end_sym store the beginning position 
and ending position of the pattern respectively. start_sym_len and 
end_sym_len store starting and ending pattern’s length respectively. 

Use one of the three field flag values to search for matches: 

TEXTSW_DELIMITER_FORWARD, TEXTSW_DELIMITER_BACKWARD, and 
TEXTSW~DELIMITER_ENCLOSE. 

□ TEXTSW_DELIMITER_FORWARD begins from first and searches for¬ 
ward until it finds start_sym and matches it forward with end_sym. 


textsw; 

♦first, *last_plus_one; 
*start_sym, *end_sym; 
start_sym_len, end_sym_len; 
field_flag; 


Matching a Span of 
Characters 
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8.10. Marking Positions 


□ TEXTSW_delimiter_backward begins from first and searches 
backward for end_sym and matches it backward with start_sym . 

□ TEXTSW_DELIMITER_ENCL0SE begins from first and expands both 
directions to match start_sym and end_sym of the next level. 

If no match is found, then text sw_match_bytes () will return a value of 
-1. If a match is found, then it will return the index of the first match. 

The following code fragment is an example of finding delimited text. Notice that 
the field_f lag value is TEXTSW_DELIMITER FORWARD. 


Textsw__index first, last_plus_one f pos; 

first* (Textsw_index) window__get(textsw, TEXTSW_INSERTION_POINT) ; 
pos = textsw_match_bytes(textsw, Sfirst, &last_j>lus_one, 

strlen( M */ M ), 

strlen("*/"), TEXTSW_DELIMITER_FORWARD) ; 

if (pos > 0) { 

textsw_set__selection(textsw, first, last_plus_one, 1) ; 
window_set(textsw, TEXTSW_INSERTION_POINT, last_plus_one, 0) ; 
} else 

(void) window__bell(textsw); 

^ - ---- > 

This code searches forward from first until it finds the starting */ and 
matches it forward with the next */. If no match is found, a bell will ring in the 
text subwindow. 


Often a client wants to keep track of a particular character, or group of characters 
that are in the text subwindow. Given that arbitrary editing can occur in a text 
subwindow, and that it is very tedious to intercept and track all of the editing 
operations applied to a text subwindow, it is often easier to simply place one or 
more marks at various positions in the text subwindow. These marks are 
automatically updated by the text subwindow to account for user and client edits. 
There is no limit to the number of marks you can add. 

A new mark is created by calling: 

Textsw_mark 

textsw_add_mark(textsw, position, flags) 

Textsw textsw; 

Textsw__index position; 
unsigned flags; 

The flags argument is either TEXTSW_MARK_DEF AULTS or 
T EXT S W_MARK_MOVE_AT_I NS ERT . The latter causes an insertion that occurs 
at the marked position to move the mark to the end of the inserted text, whereas 
the former causes the mark to not move when text is inserted at the mark’s 
current position. As an example, suppose that the text managed by the text 
subwindow consists of the two lines 
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Assume a marie is set at position 5 Oust before the i in is on the first line) with 

flags Of TEXTSW_MARK_MOVE_AT_INSERT. 

When the user selects just before the is (thereby placing the insertion point before 
the i, at position 5) and types an Bh, making the text read 



the marie moves with the insertion point and they both end up at position 6. 

However, if the flags had been TEXT SW_MARK_DEFAULT S , then the marie 
would remain at position 5 after the user typed the h, although the insertion point 
moved on to position 6. 

Now, suppose instead that the user had selected before the this on the first line, 
and typed Kep, making the text read 



In this case, no matter what flags the mark had been created with, it would end 
up at position 8, still just before the i in is. 

If a mark is in the middle of a span of characters that is subsequently deleted, the 
mark moves to the beginning of the span. Going back to the original scenario, 
with the original text and the mark set at position 5, assume that the user deletes 
from the h in this through the e in the on the first line, resulting in the text 



When the user is done, the marie will be at position 1, just before the e in te. 

The current position of a marie is determined by calling: 

Text sw_index 

textsw_find_mark(textsw, mark) 

Textsw textsw; 

Textsw_mark mark; 

An existing mark is removed by calling: 
void 

textsw_remove_mark(textsw, mark) 

Textsw textsw; 

Textsw_mark mark; 

Note that marks are dynamically allocated, and it is the client’s responsibility to 
keep track of them and to remove them when they are no longer needed. 
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8.11. Setting the Primary The primary selection may be set by calling: 

Selection 

void 

textsw_set_selection(textsw, first, last_plus_one, type) 
Textsw textsw; 

Textsw_index first, last_plus_one; 
unsigned type; 

A value of 1 for type means primary selection, while a value of 2 means secon¬ 
dary selection, and a value of 17 is pending delete Note that there is no require¬ 
ment that all or part of the selection be visible; use 
textsw_possibly_normalize () (described previously in Section 8.5, 
Editing the Contents of a Text Subwindow) to guarantee visibility. 

8.12. Dealing with Multiple By using the ‘Split View’ menu operation, the user can create multiple views of 

Views the text being managed by the text subwindow. Although these additional views 

are usually transparent to the client code controlling the text subwindow, it may 
occasionally be necessary for a client to deal directly with all of the views. This 
is accomplished by using the following routines, and the information that split 
views are simply extra text subwindows that happen to share the text of the origi¬ 
nal text subwindow. 

Textsw 

textsw_first(textsw) 

Textsw textsw; 

Given an arbitrary view out of a set of multiple views, text sw_f irst () 
returns the first view (currently, this is the original text subwindow that the client 
created). To move through the other views of the set, call: 

Textsw 

textsw__next (textsw) 

Textsw textsw; 

Given any view of the set, text sw_next () returns some other member of the 
set, or NULL if there are none left to enumerate. The following loop is 
guaranteed to process all of the views in the set: 

for (textsw=textsw_first(any_split); 

*textsw; 

textsw=textsw_next(textsw)) { 
processing involving textsw; 

1 

When you create a text subwindow take into account that your user may split the 
window. If you do something like try to enlarge the window, you will run into 
problems. 
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8.13. Notifications from a The text subwindow notifies its client about interesting changes in the 

Text Subwindow subwindow’s or text’s state by calling a notification procedure. It also calls this 

procedure in response to user actions. If the client does not provide an explicit 
notification procedure by using the attribute TEXTSW_NOTIFY_PROC, then the 
text subwindow provides a default procedure. The declaration for this procedure 
looks like: 

void 

notify_proc(textsw, avlist) 

Textsw textsw; 

Attr_avlist avlist; 

avlist contains attributes that are the members of the Text sw_action 
enumeration. 

Your notification procedure must be careful to either process all of the possible 
attributes that it can be called with or to pass through the attributes that it does 
not process to the standard notification procedure. This is important because 
among the attributes that can be in the avlist are those that cause the standard 
notification procedure to implement the Front, Back, Open, Close, and Quit 
accelerators of the user interface. 

Here is an example of a client notify procedure, and a code fragment demonstrat¬ 
ing how it would be used: 
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default_textsw_notify = 

(void (*)())window_get(textsw, TEXTSW_NOTIFY_PROC); 

window_set(textsw, TEXTSW_NOTIFY_PROC, client_notify_proc); 


The Text sw_act ion attributes which may be passed to your notify procedure 
are listed in the following table (duplicated in Chapter 19, SunView Interface 
Summary ). Remember that they constitute a special class of attributes which are 
passed to your textsw notification procedure. They are not attributes of the text 
subwindow in the usual sense, and can not be retrieved or modified using 
window_get () or window_set (). 


Table 8-2 Textsw action Attributes 


Attribute 

Value Type 

Description 

TEXT SW_ACTION_CAP S LOCK 

boolean 

The user pressed the CAPS-lock function key to change the 
setting of the CAPS-lock (it is initially 0, meaning off). 

TEXTSW_ACTION_CHANGED_DIRECTORY 

char * 

The current working directory for the process has been 
changed to the directory named by the provided string value. 

TEXTSW_ACTION_EDITED FILE 

char * 

The file named by the provided string value has been edited. 
Appears once per session of edits (see below). 

TEXTSW_ACTION_EDITED MEMORY 

none 

monitors whether an empty text subwindow has been edited. 

TEXTSW_ACTION_FILE IS READONLY 

char * 

The file named by the provided string value does not have 
write permission. 

TEXTSW_ACTION_LOADED_FILE 

char * 

The text subwindow is being used to view the file named 
by the provided string value. 

TEXTSW_ACTION_TOOL CLOSE 

(no value) 

The frame containing the text subwindow should become 
iconic. 

TEXTSW_ACTION_TOOL_DESTROY 

Event * 

The tool containing the text subwindow should exit, 
without checking for a veto from other subwindows. 

The value is the user action that caused the destroy. 

TEXT SW_ACTION_TOOL_QUIT 

Event * 

The tool containing the text subwindow should exit 
normally. The value is the user action that caused 
the exit. 

TEXTSW_ACTION_TOOL MGR 

Event * 

The tool containing the text subwindow should do the 
window manager operation associated with the 
provided event value. 

TEXTSW_ACTION_USING_MEMORY 

(no value) 

The text subwindow is being used to edit a string stored in 
primary memory, not a file. 
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The attribute TEXTSW_ACTI0N_EDITED_FILE is a slight misnomer, as it is 
given to the notify procedure after the first edit to any text, whether or not it 
came from a file. This notification only happens once per session of edits, where 
notification of TEXTSW_ACTlON_LOADED_FILE is considered to terminate 
the old session and start a new one. 

NOTE The attribute TEXTSW_ACTlON_LOADED_F ILE must be treated very care¬ 

fully. This is because the notify procedure gets called with this attribute in 
several situations: after a file is initially loaded, after any successful ‘Save 
Current File’ menu operation, after a 'Undo All Edits’ menu operation, and dur¬ 
ing successful calls to textsw_reset (), textsw_save () and 
textsw_store(). 

The appropriate response by the procedure is to interpret these notifications as 
being equivalent to: 

“The text subwindow is displaying the file named by the provided 
string value; no edits have been performed on the file yet. In addition, 
any previously displayed or edited file has been either reset, saved, or 
stored under another name.” 
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Panels 


Quick Reference, Listings and 
Summary Tables 

This chapter describes the panel subwindow package, which you can use by 
including the file <suntool/panel, h>. 

Section 1 provides a non-technical introduction to panels. Section 2 introduces 
the basic concepts and routines needed to use panels. Scrollable panels are 
covered in Section 3. Sections 4 through 9 describe the different types of panel 
items in detail, including examples. 

For examples of complete panels, see the programs filer, imagebrowser 1 and 
image browser_2, which are listed in Appendix A and discussed in Chapter 4, 
Using Windows. 

For quick reference, the next two pages are a visual index to the different effects 
possible in panels. After that come lists of the available panel and panel item 
attributes, functions and macros. Many of these are discussed in the rest of this 
chapter and elsewhere (use the Index to check). Finally, tables that summarize 
the usage of panel attributes, functions and macros are in Chapter 19, SunView 
Interface Summary: 

□ the Panel Attributes table begins on page 346; 

□ the Generic Panel Item Attributes table begins on page 347; 

o the Choice and Toggle Item Attributes table begins on page 349; 

□ the Slider Attributes table begins on page 351; 

□ the Text Item Attributes table begins on page 352; 

□ the Panel Functions and Macros table begins on page 353. 
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Page Description 

167 Messages 

168 Buttons 

173 Choice (default) 

173 Choice (custom marks) 

173 Choice (inverted) 

174 Choice (current) 

174 Choice (cycle) 

175 Choice (dial) 

175 Choice (images, menu) 

171 Choice (images) 


Example 



This action will cause unsaved edits to be lost. 


[Reset] [ Reset ] 


Drawing Mode: 0 Points a Line 0 Rectangle 0 Circle 0 Text 


Drawing Mode: Points ►Line Rectangle Circle Text 
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Page Description 
177 Toggle (vertical) 


178 Text 

179 Text (masked) 


Example 

Format Options: 

O' Long 
□ Reverse 
B'shou all files 

Name: Eduard G. Robinson 

Passuord: A******* 


183 Text with menu 


File: dervish.Inage 


ESC - Filename completion b 


- Load Inage fron file 


A S - Store Image to file 
A B - Browse directory 
A Q - Quit 


185 Slider 


Brightness: [75] 


188 


168 Button with menu 
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Introduction 

SunVIeu Model 
Windows 
Canvases 
Input 
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TTY Subulndows 
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Panel Attributes 

PANEL_ACCEPT_KEYSTROKE 

PANEL EVENT PROC PANEL LABEL BOLD 

PANE L_BACKGROUND_PROC 

PANEL FIRST_ITEM PANEL_LAYOUT 

PANEL_BLINK_CARET 

PANEL ITEM_X_GAP PANEL_SHOW_MENU 

PANEL CARET ITEM 

PANEL ITEM Y GAP 



Generic Panel Item Attributes 

PANEL ACCEPT_KEYSTROKE 

PANEL MENU CHOICE IMAGES 

PANEL_CLIENT_DATA 

PANEL_MENU_CHOICE_STRINGS 

PANEL_EVENT_PROC 

PANEL MENU_CHOICE_VALUES 

PANEL_ITEM_RECT 

PANEL_MENU_TITLE_FONT 

PANE L_ITEM_X 

PANEL_MENU_TITLE_IMAGE 

PANEL_ITEM_Y 

PANEL_MENU_TITLE_STRING 

PANEL_LABEL_X 

PANEL_NEXT_ITEM 

PANEL_LABEL_Y 

PANEL_NOTIFY_PROC 

PANEL_LABEL_BOLD 

PANEL_PAINT 

PANEL_LABEL_FONT 

PANEL_PARENT_PANEL 

PANE L_LABEL_IMAGE 

PANEL_SHOW_ITEM 

PANEL_LABEL_STRING 

PANEL_SHOW_MENU 

PANEL_LAYOUT 

PANEL_VALUE_X 

PANEL MENU CHOICE FONTS 

PANEL VALUE_Y 



Choice and Toggle Item Attributes 

PANEL_CHOICE_FONTS 

PANEL MARK IMAGE 

PANEL_CHOICE_IMAGE 

PANEL_MARK_IMAGES 

PANEL_CHOICE_IMAGES 

PANE L_MARK_X 

PANEL_CHOICE_STRING 

PANE L_MARK_X S 

PANEL_CHOICE_STRINGS 

PANEL_MARK_Y 

PANEL_CHOICE_X 

PANEL_MARK_YS 

PANEL_CHOICE_XS 

PANEL_MENU_MARK_IMAGE 

PANEL_CHOICE_Y 

PANEL_MENU_NOMARK_IMAGE 

PANEL_CHOICE_YS 

PANEL_NOMARK_IMAGE 

PANEL_CHOICES_BOLD 

PANEL_NOMARK_IMAGES 

PANEL_DISPLAY_LEVEL 

PANEL_SHOW_MENU_MARK 

PANEL_FEEDBACK 

PANEL_TOGGLE_VALUE 

PANEL LAYOUT 

PANEL VALUE 



Slider Item Attributes 

PANEL_MIN_VALUE 

PANEL SHOW RANGE P ANEL VALUE 

PANEL_MAX_VALUE 

PANEL SHOW_VALUE PANEL_VALUE_FONT 

PANEL NOTIFY LEVEL 

PANEL SLIDER WIDTH 
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Text Item Attributes 


PANEL MASK CHAR 


PANEL_VALUE_DISPLAY LENGTH 

PANEL_NOTIFY_LEVEL 


PANEL_VALUE 

PANEL_NOTIFY_STRING 
PANEL_VALUE_STORED LENGTH 


PANE L_VALUE_FONT 
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9.1. Introduction to Panels Panels contain items through which the user interacts with a program. Panels are 
and Panel Items quite flexible; you can use them to model a variety of things, including; 

□ a form consisting mainly of text items; 

□ a message window containing status or error messages; 

□ a complex control panel containing items and menus of many types. 

Panels need not be limited to the size of the subwindow they appear in. By 
attaching scrollbars to a panel, you can show a large panel within a smaller 
subwindow. The user can then bring the area of interest into view by means of 
the scrollbars. 

There are six basic types of panel items: messages, buttons, choices, toggles, 
text and sliders. Items are made up of one or more displayable components. One 
component shared by all item types is the label. An item label is either a string 
or a graphic image (i.e., a pointer to a pixrect). Button, choice, toggle, and text 
items also have a menu component. Thus the user may interact with most items 
in either of two ways: by selecting the item directly or by selecting from the 
item’s menu. 

Each item type is introduced briefly below. 

Message Items The only visible component of a message item is a label, which may be an image 

or a string in a specified font. Message items are useful for annotations of all 
kinds, including titles, comments, descriptions, pictures, and dynamic status mes¬ 
sages. 

Message items are selectable, and you may specify a notify procedure to be 
called when the item is selected. 

Button Items Button items allow the user of a program to initiate commands. Buttons, like 

message items, have a label, are selectable, and have a notify procedure. Button 
items differ from message items in that they have visible feedback for preview¬ 
ing and accepting the selection. 

Choice Items Choice items allow the user to select one choice from a list. The displayed form 

of a choice item can vary radically, depending on how you set its attributes. A 
choice item can be presented as: 

□ a horizontal or vertical list of choices, with all choices visible and the current 
choice indicated by a marie (such as a checkmark); 

□ a horizontal or vertical list of choices, with all choices visible and the current 
choice in reverse-video; 

□ a “cycle item”, or list of choices with only the current choice visible. Select¬ 
ing the item causes the next choice in the list to be selected and displayed; 

□ a dial, knob or switch with a pointer of some sort which turns to indicate one 
of several choices; 

□ a place holder for a pop-up menu, with only the label visible until the menu 
button is pressed. 
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Behind this flexibility of presentation lies a uniform structure consisting of a 
label, a list of choices, and, optionally, a corresponding lists of on-marks and 
off-marks used to indicate which choice is currently selected. 

Toggle Items In appearance and structure, toggle items are identical to choice items. The 

difference lies in the behavior of the two types of items when selected. In a 
choice item exactly one element of the list is selected, or current, at a time. A 
toggle item, on the other hand, is best understood as a list of elements which 
behave as toggles: each choice may be either on or off, independently of the 
other choices. Selecting a choice causes it to change state. There is no concept 
of a single current choice; at any given time all, some, or none of the choices 
may be selected. 

Text Items Text items are basically type-in fields with optional labels and menus. You can 

specify that your notify procedure be called on each character typed in, only on 
specified characters, or not at all. This allows an application such as a forms- 
entry program to process input on a per character, per field, or per screen basis. 

Slider Items Slider items allow the graphical representation and selection of a value within a 

range. They are appropriate for situations where it is desired to make fine adjust¬ 
ments over a continuous range of values. A familiar model would be a horizontal 
volume control lever on a stereo panel. 

9.2. Basic Panel Routines This section covers basic panel usage, including creating and sizing panels, creat¬ 
ing and positioning panel items, modifying and retrieving the attributes for 
panels and panel items, and destroying panel items. 

Creating and Sizing Panels Like all windows in SunView, panels are created by calling the window creation 

routine with the appropriate type parameter: 






Panel panel; 



panel = window_create(frame, PANEL, 0); 


< _ 




The above call will produce a panel which extends to the bottom and right edges 
of the frame. You can specify the panel’s dimensions explicitly in character 
units via WlN_COLUMNS and WIN_R0WS, or in pixel units via WIN_WIDTH 
and WIN HEIGHT. 51 


51 For a fuller discussion of subwindow sizing and layout see are in Chapter 4, Using Windows. 
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Creating and Positioning 
Panel Items 


Explicit Item Positioning 


Often you want the panel to be just high enough to encompass all of the items 
within it. After creating all of the items, and before creating any other subwin¬ 
dows in the frame, set the height of the panel by calling the macro 
window_f it_height (). This macro will compute the lowest point occu¬ 
pied by any of the panel’s items and set the panel height to that point plus a bot¬ 
tom margin of four pixels. The macros window_fit_width() to set the 
width, and window_f it () to set both the height and the width, are also pro¬ 
vided. 

To create a panel item, call: 

Panel_item 

panel_create_item(panel, item_type, attributes) 

Panel panel; 

<itemtype> item_type; 

<attribute-list> attributes; 

Values for item_type must be one of PANEL_MESSAGE, PANEL_BUTTON, 
panel_choice|PANEL_CYCLE,PANEL_TOGGLE,PANEL_TEXT, or 
PANEL_SLIDER. 

The position of items within the panel may be specified explicitly by means of 
the attributes PANEL_ITEM_X and PANEL_ITEM_Y . 52 PANEL_ITEM_X sets 
the left edge of the item’s rectangle (the rectangle which encloses the item’s label 
and value). PANEL_ITEM_Y sets the top edge of the item’s rectangle. 

All coordinate specification attributes interpret their values in pixel units. For 
simple panels and forms which do not make heavy use of images and have only 
one text font, it is usually more convenient to specify positions in character units 
— columns and rows rather than x’s and y’s. You can specify positions in char¬ 
acter units with the ATTR_ROW () and ATTR_COL () macros , 53 which interpret 
their arguments as rows or columns, respectively, and convert the value to the 
corresponding number of pixels, based on the panel’s font, as specified by 
WIN_FONT. Compare the two calls below: 


panel_create_item (panel, PANEL_MESSAGE f 

PANEL__LABEL_STRING, "Hi ! ", 
PANEL_ITEM__X, 10, 

PANEL_ITEM_Y, 20, 

0 ); 


52 Many attributes, such as those relating to item positioning, apply across all of the item types; these are 
called generic attributes. A comprehensive summary of these generic attributes is given in the Generic Item 
Attributes table in are in Chapter 19, SunView Interface Summary. 

53 ATTR ROW () and ATTR COL () are described fully in Chapter 18, Attribute Utilities. 
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panel_create_item(panel, PANEL_MESSAGE, 

PANEL_LABEL_STRING, "Hi!", 

PANEL_ITEM_X, ATTR_COL(10), 

PANEL_ITEM_Y, ATTR_ROW(20), 

0 ); 


The first will place the item at pixel location (10,20), while the second will place 
the item at row 20, column 10. 

NOTE The value computed for ATTR_ROW () includes the top margin, given by 

WIN_T0P_MARGIN, and the value computed for ATTR_COL () includes the 
left margin, given by WIN_LEFT_MARGIN. The alternate macros 
ATTR_ROWS () and ATTR_COLS () are also provided, which compute values 
that do not include the margins. 

Default Item Positioning If you create an item without specifying its position, it is placed just to the right 

of the item on the “lowest row” of the panel, where lowest row is defined as the 
maximum y-coordinate ( PANEL_ITEM_Y ) of all the items. So in the absence 
of specific instructions, items will be placed within the panel in reading order as 
they are created: beginning four pixels in from the left and four pixels down 
from the top, items are located from left to right, top to bottom. If an item will 
not fit on a row, and more of the item would be visible on the next row, it will be 
placed on the next row. The number of pixels left blank between items on a row 
may be specified by PANEL_ITEM_X_GAP, which has a default value of 10. 
The number of pixels left blank between rows of items may be specified by 
PANEL_ITEM_Y_GAP, which has a default value of 5. 

The default position for the next item is computed after an item is created. But if 
a client calls panel_set () after creating an item in such a way that the 
enclosing rectangle of the item is altered, the default position for the next item 
will not be recomputed. So, for example, 


item = panel_create_item(panel, PANEL_MESSAGE, 0); 
panel_set(item, PANEL_LABEL_STRING, "Hi", 0); 

iteml - panel_create_item(panel, PANEL_MESSAGE, 

PANEL_LABEL_STRING, "There", 
0 ); 


will result in There overlapping Hi. 

CAUTION Choice items currently have problems with item “creep.” Each time the label 
of a choice item is set, the position of the item will be evaluated. If the value’s 
position has not been fixed (with VALUE_x/Y), the value is positioned after the 
label. The problem is that the label is baseline-adjusted for a choice item. If the 
item position is not given when the label is set, the choice item will creep down 
because of the baseline adjustment. 
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Laying Out Components Within 
an Item 


Modifying Attributes 


You may also specify the layout of the various components within an item, by 
means of the attributes PANEL_LABEL_X, PANEL_LABEL_Y, 
PANEL_VALUE_X, panel_value_Y, etc. If the components are not expli¬ 
citly positioned, then the value is placed either eight pixels to the right of the 
label, if p anel_layout is PANEL_HORi ZONTAL (the default), or four pixels 
below the label, if PANEL_LAYOUT is PANEL_VERTICAL. 

This section describes how to modify the values of attributes of panels or indivi¬ 
dual panel items which have already been created. 

Since panels are a type of window, their attributes are set with window_set (). 
To set attributes of panel items, use: 

panel_set(item, attributes) 

Panel_item item; 

<attribute-list> attributes; 

A macro is provided to ease the syntax for the common operation of setting an 
item’s value (attribute PANEL_VALUE ): 

panel_set_value(item, value) 

Panel_item item; 
caddr_t value; 

Several examples of setting attributes are given here; for a complete list of the 
attributes applying to panels and items, see the tables in are in Chapter 19, Sun- 
View Interface Summary. 

To move a panel’s caret to the text item name_item: 


window_set(panel, 
PANEL_CARET_I TEM, 
name item, 0); 


To set the value of the choice item f ormat_item to the third choice (choices 

are zero-based): 

-- 

Panel_itern format_item; 
panel_set_value (format__item, 2); 


The first call below creates a message which is initially “hidden” (not displayed 
on the screen); the second call displays the message: 
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NOTE The values for string-valued attributes are dynamically allocated when they are 

set (at creation time or later). If a previous value was present, it is freed after the 
new string is allocated. This is in contrast to the storage-allocation policy for 
retrieving attributes, described in the section titled Retrieving Attributes. 


Panel-Wide Item Attributes Some attributes which apply to items may be set for all items in the panel by set¬ 

ting them when the panel is created. Such attributes include whether items have 
> menus, whether item labels appear in bold, whether items are laid out vertically 

or horizontally, and whether items are automatically repainted when their attri¬ 
butes are modified. 54 For example, the call: 


r 


\ 


panel = window_create(frame, PANEL 



PANEL_SHOW_MENU, 

FALSE, 


PANEL_LABEL_BOLD, 

TRUE, 


PANEL_LAYOUT, 

P ANEL__VERT I CAL, 


PANEL PAINT, 

PANEL_NONE, 

s, 

0); 

— ___/ 


overrides the defaults for all the attributes mentioned: any items subsequently 
created in that panel will not have menus, will have their labels printed in bold 
and their components laid out vertically, and will not be repainted automatically 
when their attributes are modified. 

NOTE When you set the attribute PANEL_LAYOUT, it will only affect the components 
in each item, not the items themselves. That is, all items in a panel will not be 
layed out vertically. 

Keep in mind that he panel-wide item attributes mentioned above are only used 
to supply default values for items which are subsequently created. This means, 
for example, that you cannot change all the item labels to bold by first creating 
the items and then setting PANEL_LABEL_BOLD to TRUE for the panel. 

Retrieving Attributes Use window_get () to retrieve attributes for a panel. To retrieve attributes 

applying to panel items, use: 

caddr_t 

panel_get(item, attribute!, optional_arg]) 

Panel_item item; 

Panel_attribute attribute; 

Panel_attribute optional_arg; 

A macro is provided to ease the syntax for the common operation of getting an 
item’s value (attribute PANEL_VALUE ): 


54 For a complete list of panel-wide item attributes, see the Panel Attributes table in are in Chapter 19, 
SunView Interface Summary. 
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Destroying Panel Items 


caddr_t 

panel_get__value (item, value) 

Panel__item item; 
caddr_t value; 

Since the *_get () routines are used to retrieve attributes of all types, you 
should coerce the value returned into the type appropriate to the attribute being 
retrieved, as in the examples below. 

To find out whether an item is currently being displayed on the screen: 


L 

int displayed; 

displayed = (int)panel_get(item, PANEL_SHOW_ITEM); 

> 

_ > 

To find out whether the caret in a panel is blinking or non-blinking: 


int blinking; 

blinking - (int) window__get (panel, PANEL_BLINK_CARET); 


To get the image for a choice item’s third (counting from zero) choice: 

r 

< 

Pixrect *image; 

image = (Pixrect *)panel_get (item, PANEL__CHOICE_IMAGE, 2); 

J 


The above example illustrates the use of the optional_arg argument, which 
is used for only a few item attributes. 

NOTE panel_get () does not dynamically allocate storage for the values it returns. 

If the value returned is a pointer, it points directly into the panel’s private data. It 
is your responsibility to copy the information pointed to. The policy for setting 
attributes is different: the values for string-valued attributes are dynamically 
allocated (see the note above under Modifying Attributes). 

To destroy a panel item (and free its associated dynamic storage), call: 

panel_destroy_item(item) ; 

Panel item item; 
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9.3. Using Scrollbars With A scrollable panel is a large panel which can be viewed through a smaller 
Panels subwindow by means of scrollbars. 

Creating Scrollbars Scrollbars come in two orientations: vertical and horizontal. The call below 

creates a panel with both vertical and horizontal scrollbars (as would be desirable 
in a long, many-columned table, for example): 

C ---\ 

panel = window_create(frame, PANEL, 

WIN_VERTICAL_SCROLLBAR, scrollbar_create(0), 
WIN_HORIZONTAL_SCROLLBAR, scrollbar_create(0), 

0 ); 

v_^ 


The values of the attributes WlN_VERTICAL_SCROLLBAR and 
win_HORIZONTAL_SCROLLBAR are the scrollbars which are returned by the 
scrollbar_create () calls. 55 

Commonly the scrollbar will remain attached to the panel for the duration of the 
panel’s existence, and there will be no need to modify the scrollbar’s attributes. 
In this simple case, there is no need to save the handle returned by 
scrollbar_create (). If you desire to destroy the scrollbar, modify its 
attributes, or detach it from one panel and attach it to another, you must either 
save the handle or retrieve it from the panel. 56 For example, to destroy a panel’s 
vertical scrollbar: 

— 

scrollbar_destroy (panel_get (panel, WIN_VERTICAL_SCROLLBAR) ) ; 
panel_set(panel, WIN_VERTICAL_SCROLLBAR, NULL, 0); 
v_> 


Scrolling Panels Which Often panels are used to display information for browsing, iconedit(l), for 

Change Size example, uses a popup panel to allow the user to browse through the images in a 

directory. The easiest way to do this is to create the panel items anew each time 
different information is displayed. For example, the iconedit function which 
fills the browsing panel first destroys any existing panel items, then creates an 
item for each image found. 

If you are going to change the size of the panel in this way, you must inform the 
scrollbar of the new size by calling the function: 

panel_update_scrolling_size(panel) 

Panel panel; 


55 The call scrollbar_create (0) produces a default scrollbar. It is usually best to create a default 
scrollbar and let the user specify how it looks via defaultsedit. You can, of course, override the user’s default 
settings by explicitly setting the scrollbar’s attributes. For a complete list of scrollbar attributes see Chapter 19, 
SunView Interface Summary . 

56 In order to save the scrollbar’s handle or reference any scrollbar attributes you must include the file 
<suntool/scrollbar.h>. 
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The correct time to call panel_update_scrolling_size () is after you 
have created all the items and given them labels. If you don’t update the 
scrollbar’s idea of the panel’s size, the size of the scrollbar’s bubble will be 
wrong. 


You may want the same panel to be scrollable at one time, and not scrollable at 
another. The code fragment below illustrates how this can be accomplished by 
attaching and detaching a scrollbar from a panel: 


Detaching Scrollbars from 
Panels 


panel = window_create(frame, PANEL, 0) ; 

(create items , do any other processing...) 

/* create scrollbar and attach it to panel */ 
sb = scrollbar_create(0); 

panel_set(panel, WIN_VERTICAL_SCROLLBAR, sb, 0); 

(panelfunctions with scrollbar...) 

/* now detach scrollbar from panel */ 

panel_set(panel, WIN_VERTICAL_SCROLLBAR, NULL, 0); 

(panel functions without scrollbar...) 

scrollbar__destroy (sb) ; 

^ ___ ) 


Note that the two packages are to be considered from the application’s viewpoint 
as independent packages which can be used together. The application, not the 
panel package, has the responsibility for creating any scrollbars. In order to free 
the application of the responsibility for destroying the scrollbar, panels, when 
they are destroyed, destroy any scrollbars attached to them. However, detaching 
a scrollbar from a panel, as in the above example, does not cause that scrollbar to 
be destroyed. The same scrollbar may be attached and detached from any 
number of panels any number of times. 

The sections which follow discuss the six item types in detail. 
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9.4. Messages 


Example 


9.5. Buttons 
Button Selection 


Button Notification 


Messages are the simplest of the item types. Their only visible component is 
their label. They have no value or menu. 

Message items, like buttons, are selectable and can have notify procedures. The 
selection behavior of messages differs from that of buttons in that no feedback is 
given to the user when a message is selected. 

In the following example, two message items are used together to give a warning 
message: 



This action ui11 cause unsaved edits to be lost. 


static short stop_array[] = { 

♦include "stopsign.image" 

}; 

mpr_static (stopsign, 64, 64, 1, stop__array) ; 

panel_create_item (panel, PANEL_MESSAGE, 

PANEL__LABE L_I MAGE, & s t op s i gn, 

0 ); 

panel_create_item (panel, PANEL_MESSAGE, 
PANEL_LABEL_STRING, 

"This action will cause unsaved edits to be lost.", 
0 ); 


You may change the label for a message item (as for any type of item) via 
PANEL_LABEL_STRING or PANEL_LABEL_IMAGE. 

Button items have a label and a menu, but no value. 

When the left mouse button is pressed over a button item, the item’s rectangle is 
inverted. When the mouse button is released over a button item, the item’s rec¬ 
tangle is painted with a grey background, indicating that the item has been 
selected and the command is being executed. The grey background is cleared 
upon return from the notify procedure. 

The procedure specified via the attribute PANEL_NOTlFY_PROC will be called 
when the item is selected. The form of the notify procedure for a button is: 

button_notify_jproc (item, event) 

Panel__item item; 

Event *event 
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Button Image Creation Utility A routine is provided to create a standardized, button-like image from a string: 

Pixrect * 

panel_button_image(panel, string, width, font) 

Panel panel; 

char *string; 

int width; 

Pixfont *font; 

where width indicates the width of the button, in character units. The value 
returned is a pointer to a pixrect showing the string with a border drawn around 
it. If width is greater than the length of string, the string will be centered in 
the wider border, otherwise the border will be just wide enough to contain the 
entire string (i.e., the string will not be clipped) The font is given by font — if 
NULL, the font for panel is used. 

Examples The first example renders the string in the default system font, found in 

/usr/lib/fonts/fixedwidthfonts/screen.r.13: 

[Reset 1 ] 


f -\ 

panel_create_item (panel, PANEL_BUTTON, 

PANEL_NOTIFY_PROC, quit_proc, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Reset", 0, 0), 
0 ); 

s_ ) 

The button below has a bold font and a seven character wide border: 

[ Reset j 

— 

bold = pf_open ("/usr/lib/fonts/fixedwidthfonts/screen.b. 12") ; 
panel_create_item (panel, PANEL_BUTTON, 

PANEL_NOTIFY_PROC, quit_proc, 

PANEL_LABEL_IMAGE, panel_button_image(panel,"Reset",7,bold), 
0 ); 

s_> 

It is often useful to associate a menu with a button. Figure 9-1 illustrates a but¬ 
ton representing an online manual. The menu over the button allows the user to 
bring up the text for the different chapters: 


Figure 9-1 Associating a Menu With a Button 


Introduction 
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To do this, you must write your own event procedure, as described in Section 
9.13, Event Handling. On receiving a right mouse button down event, display 
the menu and take the appropriate action depending on which menu item die user 
selects. For all other events, call the panel’s default event procedure. 

Here is the code to create the menu and the button, and the event procedure to 
display the menu: 

-N 

static short book_array[] = { 

♦include "book.image" 

}; 

mpr_static(book, 64, 64, 1, book_array); 

Menu menu = menu_create( MENU_NCOLS, 3, MENU_STRINGS, 


"Introduction", 
"SunView Model" 
"Windows", 
"Canvases", 
"Input", 

0 ); 


"Pixwins", 

"Text Subwindows" 
"Panels", 

"TTY Subwindows", 
"Menus", 


"Cursors", 

"Icons", 
"Scrollbars", 
"Selection Service" 
"Notifier", 0, 


panel_create_item(panel, PANEL_BUTTON, 


PANEL_LABEL_IMAGE, &book, 
PANEL_EVENT_PROC, handle_panel_event 
0 ); 


handle_j?anel_event (item, event) 
Panel_item item; 

Event *event; 


if (event_action(event) == 


MS_RIGHT St & event_is_down (event) ) { 

int chapter = menu_show(book_menu, panel, event, 0); 
switch (chapter) { 


case 1: /* Introduction */ break; 
case 2: /* Pixwins */ break; 


case 15: /* Notifier */ break 


} else 


panel_default_handle__event (item, event) ; 
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9.6. Choices 


Displaying Choice Items 


Choice items are the most flexible — and complex — item types. 57 Besides the 
label, they are composed of: 

□ a list of either image or string choices (specified via the attributes 

PANEL_CHOICE_IMAGES or PANEL_CHOICE_STRINGS ). 

□ a list of mark-images — images to be displayed when the corresponding 
choice is selected ( PANEL_MARK_IMAGES ). The default marie is a push¬ 
button with the center inverted. 

□ a list of nomark-images — images to be displayed when the corresponding 
choice is not selected ( PANEL_NOMARK_iMAGES ). The default nomarie 
image is a non-inverted push-button. 

The choices are numbered beginning with zero, and there is no restriction on the 
number of choices a single choice item may have. 

The attribute PANEL_DISPLAY_LEVEL determines which of an item’s choices 
are actually displayed on the screen. The display level may be set to: 

□ PANEL_ALL, (the default) all choices are shown; 

□ PANEL_CURRENT, only the current choice is shown; 

o PANEL_NONE, no choices are shown. Since the only way of selecting a 
choice is through the menu, this becomes a label with an associated pop up 
menu. 

If the display level is panel_CURRENT or panel_all, the choices are placed 
by default horizontally after the label. You can lay them out vertically below the 
label by setting PANEL__LAYOUT to PANEL_VERTICAL. If you want to place 
the choices or marks more precisely — in order to model a switch or some other 
special form — you can do so by setting the appropriate attribute, such as 
PANEL_CHOICE_XS,PANEL_CHOICE_YS, PANEL_MARK_XS, 

PANEL_MARK_YS, etc. 

A few words about using the various lists in choice items. The list you give for 
PANEL_CHOICE_STRINGS (or PANEL_CHOICE_IMAGES ) determines the 
item’s choices. 58 


57 For a complete list of the attributes applicable to choice items, see the Choice Item Attributes table in arc 
in Chapter 19, SunView Interface Summary. 

58 You must specify at least one choice, so the least you can specify is a single choice consisting of the null 
string. 
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The parallel lists PANEL_CHOICE_FONTS, PANEL_MARK_IMAGES, 

PANEL_NOMARK_IMAGE S, P ANEL_MARK_XS, PANEL_MARK_YS, 
PANEL_CH0ICE_XS, and PANEL_CHOICE_YS are interpreted with respect to 
the list of choices. For example, the first font given for 
PANEL_CHOiCE_FONTS will be used to print the first string given for 
panel_CHOICE_STRINGS, the second font will be used for the second string, 
and so on. 

The item below, taken from iconedit, shows how parallel lists can be abbrevi¬ 
ated: 


□ 



n 


panel__create_it em (iced_panel 
PANEL_MARK_IMAGES f 
P ANEL_NOMARK_I MAGES, 

PANE L__CHO I CE__I MAGES , 


PANEL_VALUE, 
PANEL_CHOICE_XS, 
PANEL_MARK_XS, 

PANEL_CHOICE_YS, 
PANEL_MARK_YS, 
PANEL__NOT IFY_PROC f 
0 ); 

s_ 


PANEL__CHOI CE, 

&down__triangle, 0, 

0 , 

&square_white, &square_25, 
&square_root, &square__50, 
&square_75, &square__black, 0, 
2 , 

30, 60, 90, 120, 150, 180, 0, 

34, 64, 94, 124, 154, 184, 0, 
345, 0, 

363, 0, 

proo f_ba c kground_pro c, 


The item has six choices, representing the six available background patterns for 
the proof area. Note, however, that three of the lists, — 
PANEL_MARK_IMAGES, PANEL_CHOICE_YS and PANEL_MARK_YS all 
have only one element. When any of the parallel lists are abbreviated in this 
way, the last element given will be used for the remainder of the choices. So, the 
345, 0 in the example above serves as shorthand for 345, 345, 345, 

345, 345, 345, 0. All the choice images will appear at y coordinate 345, 
all the marie images will appear at y coordinate 363, and all the choices will have 
down_t riangle as their marie image. 

NOTE You can’t specify that a choice or mark-image appear atx = 0 or y = 0 by using 
the attributes PANEL_CHOICE_XS, PANEL_CHOICE_YS, 
PANEL_MARK_xs or PANEL_mark_YS . Since these attributes take null- 
terminated lists as values, the zero would be interpreted as the terminator for the 
list. You may achieve the desired effect by setting the positions individually, 
with the attributes PANEL_CHOICE_X, PANEL_CHOICE_Y, 

PANEL_MARK_X, or PANEL_MARK_Y, which take as values the number of the 
choice or mark, followed by the desired position. 
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Choice Selection 


Choice Notification 


Choice Value 


Choice Menus 


The user can make a selection from a choice item either by selecting the desired 
choice directly, by selecting from the associated menu, or by selecting the label, 
which causes the current choice to advance to the next choice (or backup to the 
previous choice if the shift key is pressed while selecting); 

Feedback for choice items comes in two flavors — inverted, in which the current 
choice is shown in reverse video, and marked, in which the current choice is indi¬ 
cated by the presence of a distinguishing mark, such as a check-mark or arrow. 
Specified the type of feedback you want by setting panel_feedback to either 
PANEL_INVERTED or PANEL_MARKED. 

You may also disable feedback entirely, by setting PANEL_FEEDBACK to 
PANEL_NONE. 

The default feedback is PANEL_MARKED, unless the item’s display level is 
current, in which case the feedback is P ANEL_NONE. 

The procedure specified via the attribute PANEL_NOTlFY_PROC will be called 
when the item is selected. Choice notify procedures are passed the item, the 
current value of the item, and the event which caused notification: 

choice_notify__proc (item, value, event) 

Panel_item item; 
int value; 

Event *event; 


The value passed to the notify procedure is the ordinal number corresponding to 
the current choice (the choice which the user has just selected). The first choice 
has ordinal number zero. 

Choice and Toggle items are the only item types for which a menu appears by 
default. To disable the menu for a particular item, set PANEL_SHOW_MENU for 
that item to FALSE. 

Choice item menus may be used to represent either a simple menu or a checklist. 
The former is a menu of commands, which gives no indication of which com¬ 
mand was executed last; the latter is a menu of choices with a check-mark indi¬ 
cating the current choice. Set PANEL_SHOW_MENU_MARK to FALSE to obtain 
a simple menu, or TRUE to get a checklist 

NOTE The number of menu choices, if set by P ANEL_MENU_CHOICE_STRINGS or 
PANEL_MENU_CH0ICE_IMAGES, must be equal to the number of choices for 
the item. 
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Examples As a basis for our examples we’ll take the item in iconedit which allows the 

user to select the drawing mode. The item could have been presented in several 
different forms. 

The simplest call would specify the label and choices as strings, and take the 
defaults for all other attributes. All the choices will be displayed, and the feed¬ 
back will be marked, with push-buttons for the mark images: 


Drawing Mode: 0 Points Bune 0 Rectangle 0 Circle 0Text 


r 


\ 

panel_create_item (panel. 

PANEL_CHOICE, 


PANEL_LABEL_STRING, 

"Drawing Mode:", 


PANEL_CHOICE_STRINGS, 

"Points", "Line", "Rectangle", 
"Circle", "Text", 0, 


0); 







You can specify a custom mark, such as this small pointer, to indicate the current 
choice: 

Drawing Mode: Points »Line Rectangle Circle Text 


r 




\ 


static short pointer_array[] = { 




#include "pointer.pr" 

}; 

mpr_static(pointer, 16, 





16, 1, pointer_array); 



panel_create_item(panel, 

PANEL_CHOICE, 



P ANEL_LABEL_STRI NG, 

"Drawing 

Mode:", 



PANE L_MARK_I MAGE S, 

^pointer. 

0, 



PANEL_NOMARK_IMAGES, 

0, 




PANEL_CHOICE_STRINGS 

, "Points", 

"Line", "Rectangle", 




"Circle", 

"Text", 0, 



0); 




V, 




-J 


Setting PANEL_FEEDBACK to PANEL_INVERTED produces: 

Drawing Mode: Points IM'it-J Rectangle Circle Text 
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Often space on the panel is limited, and it is appropriate to save space by only 
showing the currently selected choice. You can do that by disabling feedback 
and displaying only the current choice: 


Drawing Mode: Line 


r 




panel__create__item (panel, 

PANEL_CHOICE, 


PANE L_LABEL_STRI NG, 

"Drawing Mode:", 


PANEL_CHOICE_STRINGS, 

"Points", "Line", "Rectangle", 
"Circle", "Text", 0, 


PANEL_DISPLAY_LEVEL, 

PANEL_CURRENT, 


PANEL FEEDBACK, 

PANEL_NONE, 


0); 




_y 


Such an item has the drawback of looking to the user like a text item. One solu¬ 
tion to this problem is to provide a distinguishing marie which clearly indicates 
the item’s type, as in: 

Drawing Mode: OLine 


The double-arrow image suggests a cycling motion, indicating to the user that the 
item is a choice item with more choices available. To get the cycle image, use 
the special item type PANEL_CYCLE: 59 


r 

panel_create_item (panel, 

PANE L__CY CLE, 

\ 


PANEL_LABEL_STRING, 

"Drawing Mode:", 



PANEL_CHOICE_STRINGS, 

"Points", "Line", "Rectangle", 
"Circle", "Text", 0, 



0); 



V 



-^ 


59 Note that a cycle item is simply a choice item with some attributes initialized — the display level is set to 
current and the on-mark is set to the cycle image. Once created, cycle items behave in exactly the same way as 
choice items. 
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With some effort, you can use a choice item to model a dial, as in Figure 9-2. 
Figure 9-2 A Dial-Like Choice Item 


Rect 


Line 

Points 



Circle 

Text 


Drawing Mode 


The way to make a such a dial is to make an image for each dial setting, and use 
these images as the on-marks. Place the on-marks and the choices explicitly — 
the on-marks in the center, forming the dial, and the choices around the dial’s 
perimeter: 


panel_create_item (panel, 

PANEL_CHOICE, 

P ANE L_CHO I CE__S TRING S, 

"Points' 1 , "Line", "Rect", 
"Circle", "Text", 0, 

PANEL_MARK_IMAGES, 

&dial__l, &dial_2, &dial_3, 
&dial 4, &dial 5, 0, 

PANE L_NOMARK_IMAGES, 

0 , 

PANEL_CHOICE_XS, 

7, 34, 82, 133, 145, 0, 

PANEL_CHOICE_YS, 

53, 33, 20, 33, 53, 0, 

PANEL_MARK_XS, 

66, 0, 

PANEL_MARK_YS, 

O 

o 

PANEL_LABEL_STRING, 

"Drawing Mode", 

P ANEL_LABEL__X, 

30, 

PANEL_LABEL_Y, 

65, 

PANE L_LABEL_FONT, 



pf_open ("/usr/lib/fonts/fixedwidthfonts/gallant .r. 19") , 
0 ); ‘ 

V-_---/ 


The form which is actually used in showniconeditis Figure 9-3. It employs 
vertical layout, images for the choices, and strings for the menu: 

Figure 9-3 iconedit ’s Drawing Mode Choice Item 
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r 


1 


panel_create__item (panel, PANEL_ 

CHOICE, 


PANEL_LAYOUT, 

_ PANE L_VERT I CAL , 


PANE L__CHO I CE_I MAGES , 

Spoints, &line, &rectangle, 
Scircle, &text, 0, 


PANE L_MENU_CHO I CE__S TRINGS, 

"Points", "Line", "Rectangle", 
"Circle", "Text", 0, 


P ANE L_MARK_IMAGES, 

&drawing_hand, 0, 


PANEL NOMARK_IMAGES, 

0); 

0, 

V_ 


-j 


9.7. Toggles 


Displaying Toggles 


Toggle Selection 


Toggle Notification 


Toggle Value 


Toggle items are identical in structure to choice items — they have a label and 
parallel lists of choices, on-marks and off-maries. They differ from choice items 
in certain aspects of their display options, their selection behavior and the 
interpretation of their value. These differences are highlighted below. 

Toggle items may have a PANEL_DISPLAY_LEVEL of either PANEL_ALL — 
all choices visible, or PANEL_NONE — no choices visible. The default is 
PANEL_ALL. 

Since there is no notion of the current choice for a toggle item, a display level of 
PANEL_CURRENT is not allowed. 

Toggle items, like choice items, may have either inverted or marked feedback, 
depending on the value of PANEL_FEEDBACK. The default is 
PANEL_MARKED. For inverted feedback, specify PANEL_INVERTED. 
PANEL_NONE is not allowed. 

Toggle items may be selected by clicking on the desired choice or through the 
menu. Selecting a choice causes that choice to toggle on or off (change state); 
other choices are not affected. 

If there is only one choice, it may be toggled by selecting the label; if there is 
more than one choice, selecting the label has no effect 

The parameters for the notify procedure are the same as for choice items except 
that the value passed is a bit mask instead of an integer: 

toggle_notify_proc(item, value, event) 

Panel_item item; 

unsigned int value; 

Event *event; 

The value passed to the notify procedure is a bit mask representing the state of 
the first 32 choices — if a bit is one, then the corresponding choice is on, if a bit 
is zero, then the corresponding choice is off. (The least significant bit is bit zero, 
which maps to choice zero.) 


#sun 
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Example 


Figure 9-4 illustrates an item which lets you set the -/, -r, or -a flags for the Is 
command: 

Figure 9-4 A Toggle Item 

Format Options: 

S' Long 
□ Reverse 
Ef Show all files 


format_item = panel_create_item(panel, PANEL_TOGGLE, 


PANEL_LABEL_STRING, 

"Format Options:", 

P ANEL__LAY OUT, 

PANEL_VERTICAL, 

PANEL__CHOICE_STRINGS, 

"Long", 

"Reverse", 

"Show all files", 

0 , 

0, TRUE, 

PANE L_TOGGLE__VALUE, 

P ANEL_TOGGLE_VALUE, 

2, TRUE, 

PANEL NOTIFY PROC, 

0); 

format_notify_proc, 


You can get or set the value of a particular choice — including choices beyond 
the first 32 — with PANEL_TOGGLE_VALUE. When used to set the value, this 
attribute takes two values: the index of the choice to set, and the desired value. 

In the above example, PANEL_TOGGLE_VALUE is used to initialize the first and 
third choices to TRUE. To find out the value of the third choice, you would call: 

-—-- 

value = (int) panel_get(format_item, PANEL_TOGGLE_VALUE, 2); 
-—-- 


You can also use the attribute PANEL__VALUE to set and get the state of a 
toggle’s choices. As mentioned on the previous page, a toggle’s value is a bit 
mask representing the state of the first 32 choices. To facilitate working with the 
value, you might first define names corresponding to each choices, and a macro 
to test for the corresponding bit in the value, like this: 


f 

#define 

LONG 

0 

\ 


#define 

REVERSE 

1 



#define 

SHOW_ALL 

2 



#define 

toggle_bit 

__on (value, bit) 

((value) & (1 « (bit))) 

v , 




__> 


You can then use the value in the notify procedure, as in: 
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Toggle Menus 


9.8. Text 

Displaying Text Items 


- , 

format_notify_proc(format_item, value, event) 

Panel_item format_item; 
unsigned int value; 

Event *event? 

1 

if (toggle_bit_on(value, LONG)) { 

1 

if (toggle_bit_on(value, REVERSE)) { 

1 

if (toggle_bit_on(value, SHOW_ALL)) { 

} 

} 

.___ 


Or you can retrieve the value outside of the notify procedure, as in: 


f - 

> 

unsigned value; 


value = panel_get_value (format__item) ; 


if (toggle_bit__on (value, LONG)) { 


} 


_ _ _—— - 

> 


The menu has as many lines as choices, and each line toggles when selected. In 
other words, the marie indicating “on” (PANEL_MENU_MARK_IMAGE) is alter¬ 
nated with the marie signifying “off’ (PANEL_MENU_NOMARK_lMAGE) each 
time the user selects a given line. 

To disable the menu, set PANEL_SHOW_MENU to FALSE. 


The value component of a text item is the string which the user enters and edits. 
It is drawn on the screen just after the label, as in: 

Name: Eduard G. Robinson 


panel_create_item (panel, PANEL_TEXT, 

PANEL_LABEL_STRING, "Name: ", 

PANEL_VALUE, "Edward G. Robinson", 

0 ); 


If PANEL_LAYOUT is set to PANEL_VERTICAL, overriding the default of 
PANEL_HORl ZONTAL, the value will be placed below the label. 

The number of characters of the text item’s value which are displayable on the 
screen is set via PANEL_VALUE_DISPLAY_LENGTH, which defaults to 80 
characters. When characters are entered beyond this length, the value string is 
scrolled one character to the left, so that the most recently entered character is 



Revision A, of May 9,1988 







Chapter 9 — Panels 179 


Text Selection 


always visible. As the string scrolls to the left, the leftmost characters move out 
of the visible display area. The presence of these temporarily hidden characters 
is indicated by a small left-pointing triangle. So setting the display length to 12 
in the above call would produce: 

Name: < G. Robinson 

As excess characters are deleted, the string is scrolled back to the right, until the 
actual length becomes equal to the displayed length, and the entire string is visi¬ 
ble. 

It is sometimes desirable to have a protected field where the user can enter 
confidential information. The attribute P ANE L_MAS K_CHAR is provided for 
this purpose. When the user enters a character, the character you have specified 
as the value of panel_mask_CHAR will be displayed in place of the character 
the user has typed. So setting PANEL_MASK_CHAR to “' *' ” would produce: 

Passuord: ******** 

If you want to disable character echo entirely, so that the caret does not advance 
and it is impossible to tell how many characters have been entered, use the space 
character as the mask. You can remove the mask and display the actual value 
string at any time by setting the mask to the null character. 

The maximum number of characters which can be typed into a text item 
(independently of how many are displayable) is set via the attribute 
P ANEL_VALUE_STORED_LENGTH. Attempting to enter a character beyond 
this limit causes the field to overflow, and the character is lost. The value string 
is blinked to indicate to the user that the text item is not accepting any more char¬ 
acters. 

The stored length, like the displayed length, defaults to 80 characters. 


A panel may have several text items, exactly one of which is current at any given 
time. The current text item is the one to which keyboard input is directed, and is 
indicated by a caret at the end of the item’s value. (If PANEL_BLINK_CARET 
is TRUE, the caret will blink as long as the cursor is in the panel.) Selection of a 
text item (i.e. pressing and releasing the left mouse button anywhere within the 
item’s rectangle) causes that item to become current. A text item also becomes 
current if it is displayed after being hidden — i.e. if PANEL_SHOW_iTEM is set 
to TRUE. 

You can find out which text item has the caret, or give the caret to a specified text 
item, by means of the panel attribute PANEL_CARET_ITEM. The call • 

f ---\ 

window_set (panel, PANEL_CARET_ITEM, name__item, 0) ; 
v____> 


moves the caret to name item, while 
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Text Notification 


-\ 

(Panel_item)window_get(panel, PANEL_CARET_ITEM); 
_/ 


retrieves the item with the caret. 

You can rotate the caret through the text items with the following two routines: 

panel_advance_caret(panel) 

Panel panel; 

panel_backup_caret(panel) 

Panel panel; 

Advancing past the last text item places the caret at the first text item; backing up 
past the first text item places the caret at the last text item. 

The notification behavior of text items is rather more complex than that of the 
other item types. You can control whether your notify procedure is called on 
each input character or only on selected characters. If your notify procedure is 
called, then the value it returns tells the panel package what to do — whether to 
insert the character, advance to the next text item, etc. 

When your notify procedure will be called is determined by the value of 
PANEL_NOTlFY_LEVEL. Possible values are given in the following table. 

Table 9-1 Text Item Notification 


Notification Level 

Causes Notify Procedure to be Called 

PANEL_NONE 

Never 

P ANE L_NON__P R INTAB LE 

On each non-printable input character 

PANEL_SPECIFIED 

If the input char is found in the string 


given for the attribute 


PANEL_NOTIFY_STRING 

PANEL_ALL 

On each input character 


PANEL_NOTIFY_LEVEL defaults to PANEL_SPECIFIED, and 
PANEL_N0TIFY_STRING defaults to \n\r\t (i.e., notification online-feed, 
carriage-return and tab). 

What happens when the user types a character? The panel package treats some 
characters specially. I Meta-C l . 60 ( Meta-V 1 . and I Meta-X I are mapped to the Sun- 
View functions I Copy 1 . 1 Paste I . and I Cut 1 . respectively. When the user types 
these characters, the panel package notices them and performs the appropriate 
operation, without passing them on to your notify procedure. 

The user’s editing characters — erase, erase-word, and kill — are also treated 
specially. If you have asked for the character by including it in 
PANEL_N0TIFY_STRING, the panel package will call your notify procedure. 

60 The Meta key is ( I .eft I or I Right I on the Sun-2 and Sun-3 keyboards. On the type 4 keyboard, the 1 Meta ) 
keys are marked with diamonds [ ♦ l 
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After the notify procedure returns, the appropriate editing operation will be 
applied to the value string. (Note: the editing characters are never appended to 
the value string, regardless of the return value of the notify procedure.) 

Characters other than the special characters described above are treated as fol¬ 
lows. If your notify procedure is not called, then the character, if it is printable, 
is appended to the value string. If it is not printable, it is ignored. If your notify 
procedure is called, what happens to the value string, and whether the caret 
moves to another text item, is determined by the notify procedure’s return value. 
The following table shows the possible return values: 

Table 9-2 Return Values for Text Item Notify Procedures 


Value Returned 

Action Caused 

PANEL_INSERT 

Character is appended to item’s value 

PANEL__NEXT 

Caret moves to next text item 

PANELJPREVIOUS 

Caret moves to previous text item 

PANEL_NONE 

Ignore the input character 


If a non-printable character is inserted, it is appended to the value string, but 
nothing is shown on the screen. 


If you don’t specify your own notify procedure, the default procedure 
panel_text_notif y () will be called at the appropriate time, as determined 
by the setting of PANEL_NOTlFY_LEVEL. The procedure is shown below: 

Panel_setting 

panel_text_notify(item, event) 

Panel_item item 
Event *event 

This procedure returns a panel setting enumeration which causes: 1) the caret to 
move to the next text item on I RETURN 1 or 1 TAB 1 :2) the caret to move to the 
previous text item on I SHIFT) [ RETURN) or I SHIFT) I TAB:) 3) printable char¬ 
acters to be inserted; and 4) all other characters to be discarded. 

By writing your own notify procedure, you can tailor the notification behavior of 
a given text item to support a variety of interface styles. On one extreme, you 
may want to process each character as the user types it in. For a different appli¬ 
cation you may not care about the characters as they are typed in, and only want 
to look at the value string in response to some other button. A typical example is 
getting the value of a filename field when the user presses the Load button. 

Text item notify procedures are passed the item and the event which caused 
notification: 

Panel_setting 

text_notify__proc (item, event) 

Panel_item item; 

Event *event; 


Writing Your Own Notify 
Procedure 


The input character is referenced by event_action (event). 
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For example, suppose you want to be notified only when the user types I Esc I or 
[ Control-01 into an item, but you still want them to be able to move to the next 


item, tab, or select 


lanuinam 


Create the item as shown below. 


r 





name__item = panel_create_itern (panel, PANEL__TEXT, 



P ANEL_LABE L__STR ING, 

"Enter Name Here:", 



P ANEL_NOT I FY_LE VEL, 

PANEL_SPECIFIED, 



PANEL_NOT I FY__STRI NG, 

"\n\r\t\033\03", 



P ANEL_NOT I FY_PROC, 

name_proc. 



0); 



\ 



_> 


Note that you must remember to return the appropriate value from your notify 
procedure. The easiest way to do this is to simply call the default text notify pro¬ 
cedure, and return what it returns: 

-- 

Panel_setting 
name_proc(item, event) 

Panel_item item; 

Event *event; 

{ 

switch (event_action(event)) { 

case ' 33': /* user pressed [Esc] */ 

/* special processing of escape */ 
return (PANEL__NONE) ; 

case ' 03': /* user pressed [Ctrl-C] */ 

/* special processing of*C */ 
return (PANEL_NONE) ; 

default: 

return (panel_text_notify(item, event)); 

} 

} 

>- y 


Text Value As shown in the example under Displaying Text Items, you can set the value of a 

text item at any time via PANEL_VALUE. You can also use the 
panel_set_value () macro, as in: 

panel_set_value(name_item, "Millard Fillmore"); 

s___ J 


The following call retrieves the value of name_item into name: 

---\ 

Panel_item name_item; 

char name [NAME__ITEM_MAX_LENGTH ] ; 

strcpy(name, (char *)panel_get_value(name_item)); 


Note that name_item should have been created with a 

PANEL_VALUE_STORED_LENGTH not greater than 

NAME ITEM MAX LENGTH, so the buffer name will not overflow. 
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Text Menus 

Example 


A menu may be associated with a text item by setting PANEL_SHOW_MENU to 
TRUE. 

One use of text item menus is to make any item-specific “accelerators”, or char¬ 
acters which cause special behavior, visible to the user. This usage of accelera¬ 
tors may be seen in Figure 9-5 which is taken from iconedit. The item 
labelled File: holds the name of the file being edited. In addition to typing print¬ 
able characters, which are appended to the value of the item, the user can type 
[Esc 1 for filename completion, I Control-L 1 to load an image from the file, 

I Control-S I to store an image to the file, or I Control-B I to browse the images in a 
directory. 

Figure 9-5 A Text Menu 


FIle: dervish.image “ Filename completion 


. - Load image from file 


'S - Store image to file 
S B - Browse directory 
S Q - Quit 


#define ESC 27 
♦define CTRLJL 12 
♦define CTRL_S 19 
♦define CTRL_Q 17 
♦define CTRL B 2 


panel_create_item(panel, PANEL_TEXT 
"File:", 


filename_item 

PANEL_LABEL_STRING, 

PANE L__NOT IF Y_LEVEL, 

P ANEL_NOT IF Y_PROC, 

PANE L_VALUE_D ISP LAY__LENGTH 
PANEL_SHOW_MENU, 

PANEL MENU CHOICE STRINGS, 


P ANEL__ALL , 
filename_proc, 

18, 

TRUE, 

"ESC - Filename completion" 
" ~L - Load image from file 
" ~S - Store image to file" 
" ~B - Browse Directory", 

" ~Q - Quit", 

0 , 


PANEL_MENU_CHOICE_VALUES, 


0 ); 


ESC, CTRL_L, CTRL_S, 
CTRL_B,CTRL_Q, 0, 


The last two attributes specify the menu. PANEL_MENU_CH0ICE_STRINGS is 
a null-terminated array of strings to appear as the selectable lines of the menu. 
The value that the menu returns for each of its lines is specified via 
PANEL_MENU_CHOlCE_VALUES. So if the menu line ‘X - Load image from 
file’ is selected, the menu will return the value CTRL_L. The value returned by 
the menu is passed directly to the text item, just as if it had been typed at the key¬ 
board. 
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9.9. Sliders 


Displaying Sliders 


Slider Selection 


Slider Notification 


A slider has four displayable components: the label, the current value, the slider 
bar, and the minimum and maximum allowable integral values (the range). 

When panel_SHOW_value is TRUE, the current value is shown in brackets 
after the label. The font used to render the value is PANE L_VALUE_FONT. 

The slider bar width in pixels is set with PANEL_SLIDER_WIDTH. 61 The 
m inimu m and maximum allowable values are set with PANEL_MIN_VALUE 
and PANE L_MAX_VALUE . The width of the slider bar corresponding to the 
current value is filled with grey. The slider bar is always displayed, unless the 
item is hidden (i.e., PANEL_SHOW_lTEM is FALSE). When 
PANEL_SHOW_RANGE is TRUE, the minimum value of the slider 
(P ANE L_M IN_VALUE) is shown to the left of the slider bar and the maximum 
value (PANEL_MAX_VALUE) is shown to the right of the slider bar. 

Only the slider bar of a slider may be selected. When the left mouse button is 
pressed within the slider bar or the mouse is dragged into the slider bar with the 
left mouse button pressed, the grey shaded area of the bar will advance or retreat 
to the position of the cursor. If the mouse is dragged left or right within the 
slider bar, the grey area will be updated appropriately. If the cursor is dragged 
outside of the slider bar, the original value of the slider (i.e., the value before the 
left button was pressed) will be restored. 

Slider notify procedures are passed the item, the item’s value at time of 
notification, and the event which caused notification: 

slider_notify_j?roc(item, value, event) 

Panel_item item; 
int value; 

Event *event; 

The notification behavior of a slider is controlled by PANEL_NOTIFY_LEVEL. 
When PANEL_NOTlFY_LEVEL is set to PANEL_DONE, the notify procedure 
will be called only when the select button is released within the slider bar. When 
PANEL_NOTlFY_LEVEL is set to PANEL_ALL, the notify procedure will be 
called whenever the value of the slider is changed. This includes: 

□ when the select button is first pressed within or dragged into the slider bar, 

□ each time the mouse is dragged within the slider bar, 

□ when the mouse is dragged outside the slider bar, 

□ when the select button is released. 


61 If you want to specify the width in characters, use the “column units” macro ATTR_COLS () described in 
Chapter 18, Attribute Utilities. 


Displaying Sliders 


Slider Selection 


Slider Notification 
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Slider Value The value of a slider is an integer in the range PANEL_MIN_VALUE to 

PANE L_max_value . You can retrieve or set a slider’s value with the attribute 
PANEL_VALUE. 

Example Figure 9-6 illustrates a typical slider, which might be used to control the bright¬ 

ness of a screen: 

Figure 9-6 A Typical Slider 


Brightness: [75] 



] 100 


* 


panel_create__item(panel, PANEL_SLIDER, 
PANEL_LABEL_STRING, 
PANEL_VALUE, 

PANE L_MI N__VALUE, 

PANE L_MAX_VALUE, 
PANEL_SLIDER_WIDTH, 

PANEL_NOTIFY_PROC, 


"Brightness: ”, 
75, 

0 , 

100 , 

300, 

brightness_j?roc. 


0 ); 


9.10. Painting Panels and To repaint either an individual item or an entire panel, use: 

Individual Items , , ^, , .... 

panel_paint(panel_ob]ect, paint_behavior) 

<Panel_item or Panel> panel_ob ject / 

Panel_setting paint_behavior; 

paint_behavior should be either PANEL_CLEAR, which causes the rectan¬ 
gle occupied by the panel or item to be cleared prior to repainting, or 
PANEL_NO_CLEAR, which causes repainting to be done without any prior clear¬ 
ing. 

You don’t have to call panel_paint () for items which you create at the same 
time as you create the panel — when the panel is initially displayed, each of its 
items will be painted. Note, however, that simply creating a panel item does not 
cause it to be painted. So items which you create after the panel has been ini¬ 
tially displayed will not appear until you call panel_paint ( ). 

The special attribute PANEL_PAINT is provided to allow you to control the 
“repaint behavior” of an item when one of its attributes is set. PANEL_PAINT 
has three possible values: 

□ PANEL_CLEAR — the item will be automatically cleared and repainted 
after each call to panel_set () . 

□ PANEL_NO_CLEAR — the item will be automatically repainted (without 
any prior clearing) after each panel set () call. 

a P ANEL_NONE — no automatic repainting will be done. 

The default value for panel_paint is panel_clear. Thus, in the default 
case, you do not need to call panel_paint () after calling panel_set (). 
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You can set the repaint behavior for an item when the item is created, or for all 
items in the panel when the panel is created. The item’s repaint behavior may 
not be reset after the item is created. However, you may temporarily override an 
item’s repaint behavior on any call to panel_set () by giving a different set¬ 
ting for PANEL_PAINT. The examples which follow show two possible repaint 
policies. 


Example 1: 


-- s 

iteml - panel_create_item(panel, PANEL_TEXT, 

PANEL_LABEL_STRING, "Enter Name:", 

PANEL_VALUE_DISP LAY_LENGTH, 10, 

PANEL_PAINT, PANEL_NONE, 

0 ); 

(beginprocessing events, etc...) 

panel_set(iteml, PANEL_ITEM_X, 10, PANEL_ITEM_Y, 50, 0); 
panel_set(iteml, PANEL_LABEL_IMAGE, Spixrectl, 0); 
panel_set(iteml, PANEL_VALUE_DISPLAY_LENGTH, 30, 0); 
panel_paint(iteml, PANEL_CLEAR); 

v___' 


®sun 
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Example 2: 


item2 = panel_create_itern(panel, PANEL__TEXT 


PANEL LABEL STRING 


"Enter Name:" 


PANEL_VALUE_DISP LAY_LENGTH, 10 
0 ); 


(beginprocessing events, etc...) 


panel_set(item2 


PANEL_ITEM__X, 10, 

PANE L__I TEM_Y, 50, 

PANEL PAINT, PANEL NONE 


0 ); 

panel_set(item2 


PANEL_LABEL_IMAGE, Spixrectl 


PANEL PAINT 


PANEL NONE 


0 ); 

panel_set(item2 


PANEL__VALUE_D I SPLAY_LENGTH, 30 
0 ); 


The above two examples each produce the same effect. In the first example, the 
item’s repaint behavior is set to PANEL_NONE at creation time, so it is not 
repainted automatically after the panel_set () calls, and no repainting occurs 
until the call to panel_paint (). In the second example, the item’s repaint 
behavior is the default, PANEL_CLEAR. This is overridden in the first two 
panel_set() calls, so no repainting occurs. However, it is not overridden in 
the third call to panel_set (), so repainting occurs before that call returns. 

As mentioned above, the repaint behavior for all items in a panel can be set when 
the panel is created, e.g.: 

/-\ 

window_create (frame, PANEL, PANE L_P AI NT, PANEL_NONE, 0) ; 
v_ j 

All items created in the above panel will have a repaint behavior of 
PANEL NONE. 
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9.11. Iterating Over a 

Panel’s Items 

You can iterate over each item in a panel with the two attributes 

PANEL_FIRST_ITEM and PANEL_NEXT_ITEM. A pair of macros, 
panel_each_item () and panel_end_each are also provided for this 
purpose. For example, to destroy each item in a panel you would call: 

Panel_item item; 

panel_each__item (browser, item) 
panel_destroy_item(item) ; 
panel_end_each 

^_ ) 

NOTE 

Parentheses are not required around the statements to be executed on each itera¬ 
tion. Also, a semicolon is not required after panel_end_each. 

9.12. Panel Item Client 

Data 

One attribute applicable to items of all types which should be mentioned is 

P ANEL_CL IENT_D AT A. You can use this attribute in a variety of ways. 

Peihaps the most common use is to associate a unique identifier with each item. 
This is convenient in the case where you have many items, or where you are 
creating and destroying items dynamically. If you need to pick one item out of 
all the items, you can store an identifier (or a class) with it via 

PANEL CLIENT_DATA, and then query the item directly to find out its 
identifier or class. 

The detool program in Appendix A, Example Programs, demonstrates this use of 
PANEL CLIENT DATA. The panel buttons for its number keys 0-9 share the 
same notify procedure. Each button’s PANEL_CLIENT_DATA holds the Ascn 
digit displayed on the button; when a button is pushed, the 

PANEL CLIENT_DATA is retrieved and displayed on the “screen” of the calcu¬ 
lator. This saves having a different notify procedure for every button. 

You can also use PANEL_CLIENT_DATA to associate a pointer to a private 
structure with an item. For one example of this usage, see the example in the 
next section under Writing Your Own Event Handler. Another application would 
be to link several items together into a list which is completely under your con¬ 
trol. 
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9.13. Event Handling 


Default Event Handling 


Writing Your Own Event 
Handler 


This section describes how the panel package handles events. 62 If you require a 
behavior not provided by default, you can write your own event handling pro¬ 
cedure for either an individual item or the panel as a whole. 

Using the default event handling mechanism, events are handled for all the panel 
items in a uniform way. A single routine reads the events, updates an internal 
state machine, and maps the event to an action to be taken by the item. Actions 
fall into two categories: previewing and accepting. The previewing action gives 
the user visual feedback indicating what will happen when he releases the mouse 
button. The accepting action causes the item’s value to be changed and/or its 
notify procedure to be called, with the event passed as the last argument. 


The default event-to-action mapping is given in the following table: 


Event 

Action 

Left button down or drag in w/left button down 

Begin previewing 

Drag with left button down 

Update previewing 

Drag out of item rectangle with left button down 

Cancel preview 

Left button up 

Accept 

Right button down 

Display menu & accept user’s selection 

Keystroke 

Accept keystroke if text item 


What actually happens when an item is told to perform one of the above actions 
depends on the type of the item. For example, when asked to begin previewing, 
a button item inverts its label, a message item does nothing, a slider item redraws 
the shaded area of its slider bar, etc. 63 

You may want to handle events in a way which is not supported by this default 
scheme. For example, there is no way to take any action on middle mouse button 
events. To do so you must extend the event handling functionality by replacing 
the default event-to-action mapping function for a panel or panel item. Three 
attributes have been defined for this purpose: 


Table 9-3 Panel Event Handling Attributes 


Attribute 

Argument Type 

Default Value 

PANEL_EVENT_PROC 

int (*) () 

panel_default_handle_event () 

PANE L_BACKGRO UND_P ROC 

int (*) () 

panel__default_handle_event () 

P ANEL_ACCEP T__KEY STROKE 

boolean 

FALSE 


An item’s PANEL_EVENT_PROC is called when an event falls over the item. 
The event procedure for an item defaults to that for the panel. Thus you can 
change the event procedure for all the items in a panel by specifying your own 
PANEL_EVENT_PROC for the panel before the panel items are created. The 
arguments passed to the event procedure are the item (or panel) and the event. 

62 The general SunView input paradigm, including details on the various events, is covered in Chapter 6, 

Handling Input. 

63 For particulars, see the Selection subsection under each item type. 
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The default event procedure, which implements the default event-to-action map¬ 
ping described on the previous page, is: 

panel_default_handle_event(object, event) 

<Panel_itemorPanel> object; 

Event *event; 

The panel’s PANEL_BACKGROUND_PROC is called when an event falls on the 
background of the panel (i.e. an event whose locator position does not fall over 
any item). The default panel background procedure is also 
panel_def ault_handle_event (); however, the various actions are no- 
ops for the panel. Note that this attribute only applies to a panel; it has no mean¬ 
ing for an individual panel item. 

The attribute PANEL_ACCEPT_KEYSTROKE determines whether or not an item 
or panel is interested in keystroke events. If this is TRUE, the item or panel 
under the cursor is given keystroke events as they are generated. The default 
behavior sends all keystroke events to the text item with the caret, independent of 
the cursor position. 

In addition to the three event related attributes, three event codes have been 
defined: 

□ p ANEL_EVENT_DRAG_IN — the item or panel was entered for the first 
time with one or more buttons down. 

□ P ANE L_E VENT_MOVE_IN — the item or panel was entered for the first 
time with no mouse buttons down. 

□ P ANE L_E VENT_CANCE L — the item or panel is no longer “current” so any 
operations in progress should be canceled (e.g. cancel previewing). 

The panel package will generate these events as appropriate and pass them to the 
item’s event procedure or the panel’s background procedure. 

The event-to-action mapping is performed by means of a set of action functions. 
If you haven’t specified an event procedure for the item, 
panel_default_handle_event () will map events to the appropriate 
actions by calling one of the action functions. These action functions have been 
made public so that, if you replace the event procedure for an item, you can ask 
the panel package to perform one of the default actions by calling the 
corresponding action function from your new event procedure. 

The action functions are given in the table on the following page. 
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Example 


Table 9-4 Panel Action Functions 


Definition 


Description 

panel_accept_key(object, event) 

<Panel or Panel Jit em> object; 

Event *event; 

Tells a text item to accept a keyboard 
event. Currently ignored by non-text 
panel items. 

panel_accept_menu(object, event) 
<Panel or Panel_item> object ; 

Event *event; 

Tells an item to display its menu 
and process the user’s selection. 

panel_accept_preview(object, 
<Panel or Panel Jitem> object; 
Event *event; 

event) 

Tells an item to do what it is supposed 
to do when selected, including completing 
any previewing feedback. 

panel_begin__preview (object, 
<Panel or Panel item> object; 
Event *event; 

event) 

Tells an item to begin any feedback 
which indicates tentative selection. 

pane l_cancel_p re view(object, 
<Panel or Panel item> object; 
Event *event; 

event) 

Tells an item to cancel any previewing 

feedback. 

panel__update_preview (object, 
<Panel or Panel Jit em> object; 
Event *event; 

event) 

Tells an item to update its previewing 
feedback (e.g. redraw the 
slider bar for a slider item). 


In most of the action routines, only the event’s location and shift state are of 
interest. When previewing, choices, toggles and sliders use the event’s location 
to determine the current value. Choices use the shift state to determine whether 
to advance or backup the current choice. panel_accept_key () is the only 
action function to make use of the actual event code. 

Suppose you are implementing dbxtool and want to have the buttons in the com¬ 
mand panel execute different commands depending on whether they were 
selected with the left or middle mouse button. For example, the button labeled 
next might behave as the step button if activated with the middle button. When 
the middle button is depressed, you want to preview an alternate label, and when 
it is released, you want to execute the dbx command corresponding to the pre¬ 
viewed label. 

You can get get this functionality by replacing the event procedure for each of 
the button items in the command panel. This could be done either by specifying 


a default event procedure for all the items when the panel is created: 

f 

panel = window_create(frame, PANEL, 

PANEL_EVENT_PROC, dbx event proc, 

0); 

-\ 

<_ 


or by specifying a the event procedure as each panel item is created: 

r 

panel__create_item (panel, PANEL_BUTTON, 

PANEL EVENT PROC, dbx event_proc, 

0); 
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Whenever one of the buttons gets an event, dbx_event_proc () will be 
called and can then map the events to actions as it sees fit The code for the new 
event procedure is given below. Note the use of PANEL_CLIENT_DATA to 
store the images for the two labels for each item. 


dbx_event_proc (item, event) 

Panel_item item; 

Event *event; 

{ 

struct dbx_data *dbx_data; /* data stored with each item */ 

Panel panel; 

/* First get my private data for this item. */ 

panel = (Panel) panel_get(item, PANEL_PARENT_PANEL) ; 

dbx_data = (struct dbx__data *) panel_get (item, PANEL_CLIENT__DATA) ; 

/* See if this is an event of interest. */ 
switch (event__action (event)) { 

/* middle button went up or down */ 
case MS_MIDDLE: 

if (event_is_down(event)) { 

/* middle button went down, so change the button's label 

* image to reflect its middle button action. 

*/ 

panel_set (item, PANEL_LABEL_IMAGE, dbx_data->middle_pr, 0) ; 

/* now begin the normal previewing */ 
panel_begin_preview(item, event); 

} else { 

/* middle button went up, so accept the previewing */ 
panel_accept_j?review (item, event) ; 

/* now change the image back */ 

panel_set(item, PANEL_LABEL_IMAGE, dbx_data->left_pr, 0); 

} 

break; 

/* drag into item with button down */ 
case PANEL_EVENT_DRAG_IN: 

if (window_get(panel, WIN_EVENT_STATE, MS_MIDDLE)) { 

/* middle button is down, so treat this as begin preview. 

*/ 

panel_set (item, PANEL_LABEL_IMAGE, dbx_data->middle_jpr, 0) ; 
panel_begin__preview (item, event) ; 

} 

else 

/* we weren't previewing, so 

* let the default event proc handle it. 

*/ 

panel_default_handle_event(item, event); 
break; 
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/* cancel for some reason */ 
case PANEL_EVENT_CANCEL: 

if (panel_get(item, PANEL_JLABEL_IMAGE) == 
dbx_data->middle^pr) { 

/* we were previewing — cancel it. 

*/ 

panel_cancel_preview (item, event) ; 

panel_set (item, PANEL_LABEL_IMAGE, dbx_data->left_pr, 0) ; 
} else 

/* we weren't previewing, so 
* let the default event proc handle it. 

*/ 

panel_default_handle_event (item, event) ; 
break; 

/* some other event */ 
default: 

/* we don't care about this event — let the default 
* event proc handle it. 

*/ 

panel__default_handle_event (item, event) ; 

} 

} 


The final step is to modify the notify procedure for each button to perform dif¬ 
ferent actions depending on which mouse button was released. The notify pro¬ 
cedure for the step/next button, for example, would look like: 


r 




> 


next_step_notify_j>roc (item. 

event) 




Panel_item item; 




t 

Event *event; 




if (event_action (event) 

== MS_MIDDLE) 




/* do middle button 

command, "step" */ 




else 




} 

/* do left button command, "next" */ 


< 



j 


Translating Events from In the case of a scrollable panel, the panel is larger than the subwindow in at least 

Panel to Window Space one dimension. If the panel has been scrolled, each point within the subwindow 

will have one location in the coordinate space of the panel and a different loca¬ 
tion in the coordinate space of the subwindow. Two functions are provided to 
translate event coordinates from panel space to window space, and vice versa. 

If you read your own events with window_read_event () , 64 you must 
translate the events from window space to panel space with: 


64 window_read_event () is described in Chapter 6, Handling Input. 
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Event * 

panel_event(panel, event) 

Panel panel; 

Event *event; 

To go from panel space to window space, use: 
Event * 

panel_window_event(panel, event) 
Panel panel; 

Event *event; 


Example 


Figure 9-7 illustrates the image browser from iconedit. It serves as an exam¬ 
ple of when to use panel_window_event (). If the user presses the menu 
button over an image, then he gets a menu showing the name of the file contain¬ 
ing the image: 

Figure 9-7 Image Browser Subframe Using panel_window_event () 



In order for the menu to be displayed in the correct place in a panel which has 
been scrolled, the menu’s location must be specified in the coordinates of the 
subwindow, not of the panel. 
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The browser is implemented as a panel containing buttons having the images as 
their labels. The buttons are created each time the user wants to browse a dif¬ 
ferent set of images. When each button is created, the name of the file containing 
the image is stored as the value of the button’s PANEL_CLIENT_DATA. 

Listed below is the event procedure shared by each button. There is a global 
menu containing a single menu item, image_menu_item. If the event is a 
right mouse button, the display string for this menu item is set to the file name 
which was previously stored as the button’s PANEL_CLIENT_DATA. 

Then the event is adjusted from panel space to window space, and the menu is 
displayed at the proper coordinates. If the user selects from the menu, the 
button’s notify procedure, browser_items_notif y_proc (), is called, so 
the effect is the same whether the item is selected through the menu or directly. 

-. 

browser__it ems_event_proc (item, event) 

Panel_item item; 

Event *event; 

{ 

if (event_action(event) == MS_RIGHT) { 

Event *adjusted_event; 
menu_set (image_menu_item, 

MENU_STRING, panel_get (item, PANEL_CLIENT_DATA) , 0) ; 

adjusted_event = panel_window_event(browser, event); 

if (menu_show(image_menu, browser, adjusted_event, 0)) { 
browser_items_notify_proc (item) ; 
return; 

} 

} 

panel_default_handle_event (item, event) ; 

} 

s_> 


Note that for all events other than the right mouse button, the panel’s default 
event procedure is called. 
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Alerts 


This chapter describes the alerts package, which you can use by including the file 
<suntool/alert. h> in your program. 

This chapter is divided into three logical sections. Section 1 provides a brief 
introduction to alerts. Section 2 explains the components that make up alerts. 
Sections 3 gives program fragments that introduce most of the alert attributes. 

10.1. Introduction to Alerts An alert is a pop-up frame that contains a panel to notify a user of problems or 

changes that require their attention. An alert is easily identified visually by a 
large black arrow that sweeps into the alert window from the left. A SunView 
application can use alerts to notify a user that an event has taken place or to ver¬ 
ify that a user requested some action. Each alert that pops up has full screen 
access. That is, the screen is frozen until the user responds to the alert. 

Alerts are a replacement for the menu_prompt () facility. Some programs will 
use menu prompts instead of alerts if the user disables alerts in 
def ault sedit. Menu prompts offer a simple box with text, and a maximum 
of two choices. 

Alerts, on the other hand, have a better user interface. Alerts provide an 
attention-getting alert arrow, buttons, fonts, beeps, a 3-D shadow, and so on. 
Using alerts, you can offer a user more than two choices of action. 

Summary Listing and Tables To give you a feeling for what you can do with alerts, the following page con¬ 
tains a list of the available alert attributes and functions. Many of these are dis¬ 
cussed in the rest of this chapter as they occur in the examples and elsewhere 
(use the Index to check). All are briefly described with their arguments in the 
alert summary tables in Chapter 19, SunView Interface Summary: 

□ the Alert Attributes table begins on page 316; 

□ the Alert Functions and Macros table begins on page 318; 
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Alert Attributes 

ALERT_BUTTON 


ALERT_ME S S AGE_STR I NGS_ARRAY_P TR 

ALERT_BUTTON_FONT 


ALERT_NO_BEEPING 

ALERT_BUTTON_NO 


ALERT__OPT IONAL 

ALERT_BUTTON_YES 


ALERT__P OS ITI ON 

ALERT_MESSAGE_FONT 


ALERT_P OSITION 

ALERT_MESSAGE_STRINGS 


ALERT_TRIGGER 


Alert Functions 

alert_prompt(client_frame, event, attributes) 
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Uses of Alerts 


A SunView application uses alerts to display messages to the user, who can then 
either continue, cancel, or choose a different course of action. Possible uses of 
alerts include the following: 

□ Querying whether an action was intended: “Are you sure you want to Quit?” 

□ Notifying a user of a current state: “Unrecognized file name. No files match 
specified pattern.” 


10.2. The Components of 
an Alert 


Figure 10-1 illustrates the visible components that make up an alert. Each com¬ 
ponent is described below. 


Figure 10-1 An Alert 


Alert Arrow 



Are you sure you want to Cancel window? 


. Text Message 




[Do NOT cancel window] 


Buttons 


Alert Arrow 


Each alert window is identifiable as an alert by the large black arrow that sweeps 
into the window from the left. 


Multiple-Line Text Message 

Do you really want to exit SunView? 


A multiple-line text message describes why an alert appeared and what to do in 
order to continue. For example, if the user tries to quit SunView, an alert with 
the message, “Do you really want to exit SunView?”, will pop up. 


Buttons 
[Cancel] 


Buttons make it possible to give the user a choice of actions when warning them 
that an event has taken place. Each button is associated with a string that 
specifies an action. 

Many alerts have a default button which is indicated by a double outline (as in 
the Confirm button above). If an alert has a default button, then the pointer will 
jump to this button when the alert appears, so that clicking LEFT will take the 
default action. The pointer is moved back to its original position when the alert 
goes away. The user can disable pointer jumping by setting 
SunView!Alert Jump Cursor to disabled in def ault sedit. 
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Positioning 

Beeping 


10.3. alert_prompt () 


10.4. Building an Alert 


You have three choices for alert placement. The alert may be screen-centered, 
client-centered, or client-offset. 

An alert may be specified to pop up with or without a beep. The default is to 
come up beeping the number of times that is specified in def ault sedit. You 
may set your alert to come up without a beep even if the user’s default 
SunView!Alert_B ell entry in def ault sedit is to come up beeping. 

There is only one function in the alert package, alert_prompt <); it creates 
an alert, pops it up on the screen, handles user interaction, then takes down the 
alert and returns a value. 

int 

alert_j?rompt (client_frame, event, attributes) 

Frame c 1 ient_f rame ; 

Event *event 

<attribute-list> attributes; 

alert_prompt () displays an alert whose appearance and behavior is 
specified by the attribute value list attributes. It does not return a value 
until the user pushes a button in the alert or the default trigger event or its 
accelerator is seen. By default the alert is positioned over the center of 
client_frame. 

If you supply a pointer to an event as event, it will be filled in with the user 
event which dismissed the alert. For example, if the users pushes a button by 
clicking LEFT, event_action (event) will be MS_LEFT. 6 ^ 

The possible status values which alert_prompt () returns are: 

□ ALERT_YES — the user pushed the “yes” alert button 

□ ALERT_NO — the user pushed the “no” alert button 

□ ALERT_FAILED — the alert_prompt () failed for some reason 

□ alert_triggered — a triggered response occurred 

□ Some other integer — the user pushed some other button than “yes” or “no.” 

This section contains code fragments that illustrate most of the attributes for the 
alerts package. For a complete list and explanation of the alert attributes, see 
Chapter 19, SunView Interface Summary. Each code fragment described below 
is organized as follows: 

□ Attributes introduced in the code are described 

□ An illustration of the alert box is given 

□ The code is listed and described. 


65 See Chapter 6, Handling Input for an explanation of the Events. 
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For a complete program example using alerts, see filer in Appendix A, Example 
Programs. 

Example 1 — Messages and This section gives two code fragments in order to illustrate the different button 
Simple Buttons attributes. The buttons allow the user to choose an action. Each alert may contain 

one or more buttons; the default is for no buttons. 

Each button has a name and an associated value. When a user pushes a button, 
the value associated with the button is returned. 

The following attributes are used in the first code fragment. STRINGS"" 
ALERT_MESSAGE_STRINGS 

The ALERT_MESSAGE_STRINGS attribute specifies a string or strings to be 
displayed in the message area of the alert panel. 

An example of the syntax for a message is: 

ALERT_ME S SAGE_STRINGS, 

"The text has been edited.", 

"Empty Document will discard these edits. Please confirm", 

0 , 

The ALERT_BUTTON attribute displays a string in a button and associates a 
value to it. The value specified with the string is returned when the button is 
pushed. The value may be any integer, but should not be one of the values 
predefined by the alerts package ( ALERT_YES, alert_NO, ALERT_FAILED, 
or ALERT_TRIGGERED ). Figure 10-2 illustrates an alert that was built using 
the attributes ALERT BUTTON. It contains four buttons and one text string. 

This example asks the user what part of the country they are from. The program 
fragment is listed below. 

Figure 10-2 A Simple Alert 



result = alert_prompt( 

(Frame) client_frame, 

(Event*) NULL 
ALERT_ME S SAGE_S TRINGS 

"What part of the country are you from?", 
0 , 


ALERT_BUTTON, 

"North", 

101, 

ALERT_BUTTON, 

"East", 

102, 

ALERT_BUTTON, 

"West", 

103, 

ALERT_BUTTON, 

"South", 

104, 
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Yes and No Buttons 


switch (result) { 


case 101: 
/^handle 

case 

for 

someone 

from 

the 

North*/ 

break; 
case 102: 
/*handle 

case 

for 

someone 

from 

the 

East*/ 

break; 
case 103: 
/^handle 

case 

for 

someone 

from 

the 

West*/ 

break; 
case 104: 
/*handle 

case 

for 

someone 

from 

the 

South*/ 

break; 
case ALERT_ 

FAILED: 






/* 

* Possibly out of memory or fds; 

* attempt to get information another way 
*/ 

break; 


Usually you will want to map your buttons to “yes” and “no” actions. To make 
this possible, two special buttons are triggered by predefined keyboard accelera¬ 
tors. Yes (confirm, do it) is mapped to the I Return I key. No (cancel, don’t do it) 
is mapped to the I Stop 1 key (usually [ LI 1 ). 

The SunView event name for yes is ACTI0N_D0_IT. The SunView event 
name for no is ACT I0N_ST0P. 

The following attributes are used in this example: 

The ALERT_BUTTON_YES attribute associates a string with the accelerated 
YES button. The value ALERT_YES is returned by alert_prompt () if the 
user pushes this button, or types I Return 1 . Only one instance of this attribute is 
allowed; subsequent instances are ignored. 

The YES button image will have a different button image than the other buttons. 
It will appear as a regular button image with a double outline. 

An example of the syntax is: 

ALERT_BUTTON_YES, "Confirm, discard edits". 

The alert_button_no attribute associates a string with the accelerated NO 
button. The value returned if the user pushes this button, or types I Stop I , will be 
ALERT_NO. Only one instance of this attribute is allowed; subsequent instances 
are ignored. 
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An example of the syntax is: 

ALERT_BUTTON_NO, "Cancel", 

Figure 10-3 illustrates the alert that is generated by the following code. It con¬ 
tains two buttons and two text strings. The buttons give the user two choices: to 
empty a document, discarding any edits they may have made, or to cancel the 
operation completely. 

Figure 10-3 A YES/NO Alert 


The text has been edited. 

Empty Document will discard these edits. Please confirm. 






int result; 

result = alert_prompt( 

(Frame)window,(Event*)NULL, 

ALERT__ME S SAGE_STR INGS, 

"The text has been edited.", 

"Empty Document will discard these edits.\ 
Please confirm.", 

0 , 

ALERT_BUTTON_YES, "Confirm, discard edits", 

ALERT_BUTTON_NO, "Cancel", 

0 ); 

switch(result){ 
case ALERT_YES: 

/*discard edits*/ 
break; 

case ALERT_NO: 

/♦cancel the Empty Document request */ 
break; 

case ALERT_FAILED: 
break; 



Revision A, of May 9, 1988 
















206 SunView 1 Programmer’s Guide 


Example 2 — Changing Fonts The default font used for alert message text is the Client Frame’s font, if one has 

been specified; or else it is the same as SunView/Font. The default font for alert 
buttons is the same as that specified for menus in Menus/Font in defaultsedit, or 
screen.b.14, if no default is specified. 

You may prefer to use different fonts within alerts. For example, you might want 
to set off the text in an alert box from the text in the Client’s frame by using the 
bold version of the Client Frame’s default font. 

The ALERT_MESSAGE_FONT and ALERT_BUTTON_FONT attributes con¬ 
trol the font setting for the alert message text and alert buttons, respectively. 

Figure 10-4 illustrates an alert in which the message string is printed in 
courier.b.16. The code fragment shown below it illustrates how to set the 
attribute’s value using the font library. It also illustrates the use of multiple mes¬ 
sage strings. 

Figure 10-4 An Alert with Boldface Message Strings 



Example 3 — Using Triggers Often you will want to give the user the choice of using mouse buttons or key¬ 
board accelerators instead of push buttons to respond to an alert. Triggers give 
you this option by making it possible to specify an accelerator or mouse action 
for a choice. 

For example, the text window uses an alert to ask the user where to split a win¬ 
dow. A left mouse button click is the trigger that responds to this alert. 
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The following attribute is used when specifying a trigger: 

The ALERT_TRIGGER attribute allows the application to specify a SunView 
event which should cause the alert to return. The default is not to return a value 
unless a button has been pushed or the other YES/NO accelerators are seen. 
When an event is triggered, the value returned will be ALERT_TRIGGER. An 
example of the message syntax is as follows. 

ALERTJTRIGGER, event. 

Figure 10-5 illustrates the alert that is generated by the following code. This alert 
contains one button and a triggered response. When this alert comes up, the user 
may split the existing window into two windows, or can dismiss the alert by 
pushing the Cancel New Window button. This example also shows how alerts 
can effectively use an event to collect information about the way a user reacted to 
an alert. See Chapter 6, Handling Input, for a full explanation and list of all pos¬ 
sible events. 


Figure 10-5 An Alert Using Triggers and Events 



Move pointer to where new view should 
begin, then click the left mouse button. 


Otherwise, push "Cancel Split View". 


[Cancel Split View] 
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---- 

Event event; 
int result; 

result = alert_prompt( 

(Frame)window, 

&event, 

ALERT_NO_BEEPING, 1, 

ALERT_MESSAGE_STRINGS, 

"Move pointer to where new window should", 

"appear, then click the left mouse button.", 

"Otherwise, push \"Cancel New Window."\, 

0 , 

ALERT_BUTT0N_N0, "Cancel New Window", 

ALERTJTRIGGER, MS_LEFT, 

0 ); 

switch (result) { 

case ALERT_TRIGGERED: 

(void) create_new_window_at_pos(event_x(Sevent), 

event_y(&event)), 

break; 

case ALERT__N0: 

break; /* don't create new window */ 
case ALERT_FAILED: 

/* alert failed, possibly out of memory or fds */ 

} 

v_ / 


You may specify in your code to have an alert pop up without a beep as shown 
above. Generally, beeping is reserved for any event which occurs unexpectedly. 
If the alert is in response to a user request, it should not beep. 

The following attribute is used to specify no beeping for an alert. 

The ALERT_NO_BEEP ING attribute allows the SunView application to specify 
that no beeping should take place regardless of def aultsedit setting. The 
default for this option is FALSE; that is, beep as many times as the defaults data¬ 
base specifies. 
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TTY Subwindows 


The tty (or terminal emulator) subwindow emulates a standard Sun terminal, the 
principal difference being that the row and column dimensions of a tty subwin¬ 
dow can vary. You can run arbitrary programs in a tty subwindow; perhaps its 
main use is to run a shell within a window. 

To see tty subwindows in use, run the standard tools shelltool(l) and 
gfxtool(l). 

Header Files Programs using tty subwindows must include the file <suntool/tty. h>. 

Summary Listing and Tables To give you a feeling for what you can do with tty subwindows, the following 

page contains lists of the available tty subwindow attributes, functions and mac¬ 
ros. Many of these are discussed in the rest of this chapter and elsewhere (use the 
Index to check). All are briefly described with their arguments in the tty subwin¬ 
dow summary tables in Chapter 19, SunView Interface Summary : 

□ the TTY Subwindow Attributes table begins on page 376; 

□ the TTY Subwindow Functions table begins on page 376; 

□ the TTY Subwindow Special Escape Sequences table begins on page 377. 
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TTY Subwindow Attributes 

TTY_ARGV TTY_PAGE_MODE 

TTY CONSOLE TTY QUIT ON CHILD DEATH 


TTY Subwindow Functions 

ttysw_input (tty, buf, len) _ ttysw_output (tty, buf, len) 
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11.1. Creating a TTY 
Subwindow 


11.2. Driving a TTY 
Subwindow 


ttysw_input() 


Like all SunView windows, you create a tty subwindow by calling 
window_create () with the appropriate type parameter, as in: 


/— 




Tty tty; 



tty = window^create(frame, TTY, 0); 


V. 


J 


By default, the tty subwindow will fork a shell. If you want to start the tty 
subwindow with another program, say vi, you can do so by specifying the name 
of the program to run via the TTY_ARGV attribute: 

r~ -\ 

♦include <suntool/sunview.h> 

♦include <suntool/tty.h> 

char *my_argv[] = { "vi", 0 }; 

main () 

{ 

Tty tty; 

Frame frame; 

frame = window_create(0, FRAME, 0) ; 

tty = window_create(frame, TTY, TTY_ARGV, my_argv, 0) ; 
window_main_loop(frame); 

} 

v_ > 


NOTE You can only have one tty subwindow per process. 

You can drive the terminal emulator programmatically. There are procedures 
both to send input to the terminal emulator (as if the user had typed it in the tty 
subwindow) and to send output (as if a program running in the tty subwindow 
had output it). The two effects are similar to the mapi / mapo functions in 
' / . ttyswr c that permit a user to bind a character sequence to a function 
key. 66 

You can send input to a tty subwindow programmatically with the function: 
int 

ttysw_input(tty, buf, len) 

Tty tty; 
char *buf; 
int len; 

ttysw__input () appends the character sequence in buf that is len charac¬ 
ters long onto tty’s input queue. It returns the number of characters accepted. 
The characters are treated as if they were typed from the keyboard. 
ttysw_input () provides a simple way for a window program to send input to 
a program running in its ttysubwindow. 


66 See shelltool(l) in the SunOS Reference Manual. 
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ttysw_input() 


Example: tty Jo 


11.3. TTY Subwindow 
Escape Sequences 

Standard ANSI Escape 
Sequences 


Use ttysw output () to output to a tty subwindow, 
int 

ttysw_output(tty, buf, len) 

Tty tty; 
char *buf; 
int len; 

tt ysw_output () runs the character sequence in buf that is len characters 
long through the terminal emulator of tty. It returns the number of characters 
accepted. The effect is similar to executing 

—'—~— --- - ——'— - —— - - -— ‘ ' 

echo character_sequehce > /dev/ttyN 

where ttyN is the pseudo-tty associated with the tty subwindow. One use of 
ttysw_output () is to send the escape sequences listed in the next section to 
the tty subwindow. 


Appendix A, Example Programs, gives the listing for tty Jo, a program which 
uses tty_output () to output strings of characters to a tty subwindow. 


The tty subwindow accepts the same ANSI escape sequences as the raw Sun con¬ 
sole, 67 with the following few exceptions: 

□ The effect of the bell control character CTRL-G (0x07) in a tty subwindow 
depends on how the user has set the two options Audible_Bell and 
Visible Bell in the SunView category in def ault sedit(l). If 
Audible Bell is Enabled, the bell will ring. If Visible Bell is Enabled, the 
window will flash. 

□ The graphics rendition sequences ESC [ 4m (underline) and ESC [ lm (bold 
“extra-bright”) operate correctly. On the Sun console, these sequence 
always invert subsequent characters, whereas the tty subwindow only inverts 
when sent ESC [ 7m (stand-out). 

□ The effect of the bold “extra-bright” graphics rendition sequence ESC [ lm in 
a tty subwindow depends on the user’s setting for the Boldstyle option in 
the Tty category of def ault sedit. 

□ Unsupported graphics rendition mode escape sequences have the same effect 
as that chosen for bold “extra-bright”. On the Sun console, everything 
inverts. 

□ The Set Scrolling sequence ESC [ 0r, which enables vertical wrap mode on 
the Sun terminal, has no effect in a tty subwindow. 


61 See the conso le(4s) manual page in the SunOS Reference Manual for a full list of escape sequences. 
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□ You can modify termcap (5) if you need further control over what gets 
displayed in the different modes. The two-character termcap symbols for 
each of the modes are: 

so standout 
us underline 
md bold (extra bright) 


Special Escape Sequences Escape sequences have been defined by which the user can get and set attributes 

of both the tty subwindow and the frame which contains it For example, the 
user can type an escape sequence to open, close, move or resize the frame, 
change the label of the frame or the frame’s icon, etc. These escape sequences 
are described in Table 19-33, TTY Subwindow Special Escape Sequences , in 
Chapter 19, SunView Interface Summary. 

Example: tty Jo For an example of setting the frame’s label via a tty subwindow escape sequence, 

see the program tty Jo, listed in Appendix A, Example Programs. 


11.4. Reading and Writing You cannot use the tty subwindow’s file descriptor returned by win_fd to read 

to a TTY Subwindow and write characters to it. You can use TTY_TTY_FD attribute to get the file 

descriptor of the pseudo-tty associated with the tty subwindow. You can then 
use this to read and write to the pseudo-tty using standard UNIX I/O routines. 
Note that TTY_TTY_FD is the file descriptor of the pseudo-tty, not the file 
descriptor of the tty subwindow returned by WIN_FD. The latter is used for 
low-level window manipulation procedures. 


11.5. The Program in the 
TTY Subwindow 


You use the TTY_ARGV attribute to pass the name of the program to run to the 
tty subwindow. The program runs as a forked child in the tty subwindow. 


TTY_P ID You can use TTY_P ID to monitor the state of the child process running in the tty 

window via the Notifier using L notify_interpose_wait3_func() • The client’s 
wait 3 () function gets called when the state of the process in the tty subwin¬ 
dow changes. The setup is something like this: 


r 




#include <sys/wait.h> 



static Notify__value my_wait3(); 



ttysw = window_create(base_frame, 

TTY, 


TTY__QU I T_ON_CH I LD_DEATH, 

FALSE, 


TTY ARGV, 

my_argv. 


0); 



- child_j?id = (int) window_get (ttysw. 

TTY_PID); 


notify_interpose_wait3_func(ttysw. 

my_wait3, child_pid); 

Vs 


j 


The wait3 () function can then do something useful, such as destroying the 
tty window or starting up another process in the tty subwindow. Here is a code 
fragment that detects the death of its tty subwindow’s child. It turns off the 
default behavior of a tty subwindow, which is to quit when the child process dies. 
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static Notify_value 

my_wait3(ttysw, pid, status, rusage) 

Tty ttysw; 

int pid; 

union wait *status; 

struct rusage *rusage; 

{ 

int child_j?id; 

notify_next_wait3_func(ttysw, pid, status, rusage); 
if (! (WIFSTOPPED(*status))) { 

window_set(ttysw, 

TTY_QUI T_ON_CH I LD_DE ATH, FALSE, 

TTY__ARGV, my_a r gv, 

0 ); 

child_pid = (int)window_get(ttysw, TTY_PID); 
notify_interpose_wait3_func(ttysw, my_wait3, child__pid) ; 

} 

return NOTIFY_DONE; 

) 


You can set TTY_PID as well as get it, but if you set it then you are responsible 
for setting the notif y_interpose_wait3_f unc () to catch the child’s 
death, and for making the standard input and standard output of the child go to 
the pseudo-tty. 

Talking Directly to the TTY If you set TTY_ARGV to TTY_ARGV_DO_NOT_FORK, this tells the system not 

Subwindow to folk a child in the tty subwindow. In combination with TTY_FD, this allows 

the tool to use standard I/O routines to read and write to the tty subwindow. 68 
This simplifies porting terminal-oriented graphics programs, which interact with 
the user on the model of write a prompt ... read a reply , to SunView. However, 
in most cases you should redesign programs to use a real windowing interface 
made up of SunView components. 

An Example The typein program in Appendix A, Example Programs reads and writes directly 

to its tty subwindow, using SunView’s window_main_loop () control struc¬ 
ture. 

The following example preserves the flow of control of a typical UNIX applica¬ 
tion, using notif y_do_dispatch () to ensure that the Notifier gets called. 
Read Section 17.6, Porting Programs to SunView, for more information on using 
the Notifier in this way. 


♦define BUFSIZE 1000 
static int my_done; 

static Notify_value 
my_notice_destroy(frame, status) 
Frame frame; 

Destroy_status status; 


68 This capability makes obsolete the work-around required 


in the 3.0 and 3.2 releases of SunView if you 


m sun 
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if (status != DESTROY_CHECKING) { 
my_done = 1 ; 

(void)notify_stop(); 

} 

return (not ify_next_destroy_func (frame, status)); 

} 

main(argc, argv) 
int argc; 

char *argv[]; 

{ 

Frame ba s e_f ra me; 

Tty ttysw; 

int tty_fd; 

char buf[BUFSIZE]; 

my_done = 0; 

base_frame = window_create (NULL, FRAME, 

FRAME_ARGC_PTR_ARGV, & a rgc, argv, 

0 ); 

ttysw = window_create (base_frame, TTYSW, 

TTY_ARGV, TTY_ARGV_DO_NOT_FORK, 

0 ); 

tty__fd = (int) window_get (ttysw, TTY_TTY_FD); 
dup2 (tty_fd, 0); 
dup2(tty_fd, 1); 

(void) notify_interpose__destroy_func (base_frame, my_notice_destroy); 
window_set (base__frame, WIN_SHOW, TRUE, 0) ; 

(void) notify__do_dispatch () ; 

puts (promptJo user) ; 

while (gets(buf)) { 

if (my_done) /* continue until destroyed */ 
break; 

/* 

* This is where the meat of the program 

* would be if this were a real program. 

*/ 

puts (buf); 

} 

exit(0); 


wanted a window program to read and write from its own tty subwindow. 
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Menus 


The SunView menu package allows you to chain individual menus together into 
a collection known as a walking menu. A menu contains menu items, some of 
which may have a small arrow pointing to the right. This indicates to the user 
that if he or she slides the mouse to the right of that item, a pull-right menu will 
appear. Menus can be strung together in this fashion, so that the user “walks” to 
the right down the chain of menus in order to make a selection. 

The definitions necessary to use walking menus are found in the file 
<suntool/walkmenu. h>, which is included by default when you include 
the file <suntool/sunview ,h>. 

The most useful sections to read first are the first three. Section 12.1, Basic 
Menu Usage, introduces the basic routines and gives some simple examples. 
Section 12.2, Components of Menus & Menu Items, outlines the components of 
menus and menu items and introduces common terms. Section 12.3, Examples, 
gives more examples of using menus. Section 12.7, Callback Procedures, is for 
advanced users who need to understand the subtleties of the callback mechanism. 

The listing for font menu, a program which builds on some of the examples 
given throughout the chapter, is given in Appendix A, Example Programs. 

Summary Listing and Tables To give you a feeling for what you can do with menus, the following two pages 

list the available menu attributes, functions and macros. Many of these are dis¬ 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the menu summary tables in Chapter 
19, SunView Interface Summary: 

□ the Menu Attributes table begins on page 335; 

□ the Menu Item Attributes table begins on page 339; 

□ the Menu Functions table begins on page 341. 
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Menu Attributes 

MENU_ACTION_IMAGE 


MENU_LAST_EVENT 

MENU_ACTION_ITEM 


MENU_LEFT_MARGIN 

MENU_APPEND_ITEM 


MENU_MARGIN 

MENU_BOXED 


MENU_NCOLS 

MENU_CENTER 


MENU_NITEMS 

MENU_CLIENT_DATA 


MENU_NROWS 

MENU__COLUMN_MAJOR 


MEN U__NOT IF Y__P ROC 

MENU_CLIENT__DATA 


MENU_NTH_ITEM 

MENU_DESCEND_FIRST 


MENU_PARENT 

MENU_DEFAULT 


MENU_P ULLRI GHT_DELTA 

MENU_DEFAULT_I TEM 


MENU_PULLRIGHT_IMAGE 

MENU_DEFAULT_SELECTION 


MENU_P ULLRI GHT_I TEM 

MENU_F I RST_EVENT 


MENU_REMOVE 

MENU_FONT 


MENU_REMOVE_ITEM 

MENU_GEN_PROC 


MEN U_RE P LACE 

MENU_GEN__P ULLRI GHT_I MAGE 


MENU_REP LACE__I TEM 

MENU_GEN_PULLRIGHT_ITEM 


MENU_RIGHT_MARGIN 

MENU_IMAGE_ITEM 


MENU_SELECTED 

MENU_IMAGES 


MENU_SELECTED__I TEM 

MENU_INITIAL_SELECTION 


MEN U_SH AD OW 

MENUJE NITIAL_SELECTION_EXPANDED 


MENU_STAY_UP 

MENU_I NITI AL_SELECT I ON__SELECTED 


MENU_STRINGS 

MENU_INSERT 


MENU__STRI NG_I TEM 

MENU_INSERT__ITEM 


MENU_TITLE_IMAGE 

MENU_ITEM 


MENU_TITLE_ITEM 

MENU_JUMP_AFTER_NO_SELECTI ON 


MENU_TYPE 

MENU_JUMP_AFTER_SELECTION 


MENU_VALID_RESULT 



Menu Item Attributes 

MENU_ACTION_IMAGEt 


MENU_INACTIVE 

MENU_ACTION_ITEMf 


MENU_INVERT 

MENU_ACTION_PROC 


MENU_LEFT_MARGINt 

MENU_APPEND_ITEMf 


MENU_MARGINt 

MENU_BOXEDf 


MENO_PARENTf 

MENU_CENTERf 


MENU_PULLRIGHT 

MENU_CLIENT_DATAt 


MENU_P ULLRIGHT_IMAGEf 

MENU_FEEDBACK 


MENU_P ULLRIGHT_ITEMf 

MENU_FONTf 


MENU_RELEASE 

MENU_GEN_PROC| 


MENU_RELEASE_IMAGE 

MENU_GEN_PROC_IMAGE 


MENU_RIGHT_MARGINf 

MENU_GEN_PROC_ITEM 


MENU_SELECTEDf 

MENU_GEN_PULLRIGHT 


MENU_STRINGf 

MENU_GEN_PULLRIGHT_IMAGEf 


MENU_STRING_ITEMf 

MENU_GEN_PULLRIGHT_ITEMf 


MENU_TYPEf 

MENU_IMAGE 


MENU_VALUE 

MENU_IMAGE_ITEMf 
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_ Menu Functions _ 

menu_create(attributes) 
menu_creat e__item (attributes) 
menu_destroy (menu__ob ject) 

menu_destroy__with_proc (menu_ob ject, destroy_proc) 
void (*destroy_j?roc) () ; 
menu_find(menu, att ributes) 
menu_set(menu_object, attributes) 
menu_show(menu, window, event, 0) 
menu_return_item (menu, menu_item) 
menu return_value (menu, menu_item) 
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12.1. Basic Menu Usage The basic usage of menus is to first create the menu with menu_creat e (), 

then display it when desired with menu_show (): 

Menu 

menu_create(attributes) 

<attribute-list> attributes; 

caddr_t 

menu_show(menu, window, event, 0) 

Menu menu; 

Window window; 

Event *event; 

Like the creation routines for other SunView objects, menu_create () takes a 
null-terminated attribute list and returns an opaque handle, menu show () 
displays the menu, gets a selection from the user, and, by default, returns the 
value of the menu item the user has selected, window is the handle of the win¬ 
dow over which the menu is displayed; event 69 is the event which causes the 
menu to come up. The final argument is provided so that attributes may be 
passed in the future; at present it is ignored. 

Use the routines menu_set () and menu_get () to modify and retrieve the 
values of attributes for both menus and menu items: 

int 

menu_set(menu_object, attributes) 

<Menu or Menujtem> menu_ob ject; 

<attribute-list> attributes ; 

caddr_t 

menu_get(menu_object, attribute[, optional_arg]) 

<Menu or Menu_item> menu_ob ject; 

Menu_attribute attribute; 
caddr_t optional_arg; 

All the attributes applying to menus and menu items are listed in the two 
corresponding tables Menu Attributes and Menu Item Attributes in in Chapter 19, 
SunView Interface Summary. Common attributes applying to both menus and 
menu items appear in both tables. 

The pages which follow contain three examples of basic menu usage. 


69 Canvases and panels have their own coordinate spaces separate from the window’s coordinate space. 
Note that event is in the coordinate space of the window, not of the canvas or panel. 
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Let’s take a very simple example — a menu with two selectable items 
represented by the strings ‘On’ and ‘Off: 

- 

on_off_menu = menu_create(MENU_STRINGS, "On", "Off", 0, 

0 ); " 

V_ 

The attribute MENU_STRINGS takes a list of strings and creates an item for each 
string. Note that the first zero in the above call terminates the list of strings, and 
the second zero terminates the entire attribute list. 

CAUTION The menu package, in contrast to the panel package, does not save strings 
which you pass in. So you should either pass in the address of a constant, as in 
the example above, or static storage, or storage which you have dynamically allo¬ 
cated. 


Typically you call menu_show () from an event procedure, 70 upon receiving 
the event which is to cause display of the menu. In the code fragment below, we 
display the menu on right button down: 


/— 

case MS_RIGHT: 

> 


menu_show(on_of f_menu, window, event, 0); 



break; 


V 


j 


menu_show (), by default, returns the value of the item which was selected. If 
the item was created with MENU STRINGS its value defaults to its ordinal posi¬ 
tion in the menu, starting with 17 1 So in the above example, selecting ‘On’ 
would cause 1 to be returned, while selecting ‘Off would cause 2 to be returned. 

You can specify that menu_show () return the item itself, rather than return the 
value of the selected item. Do this by setting MENU_NOTlFY_PROC to the 

predefined notify procedure 72 menu_return_item (), as in: 
— 

menu_set (on_of f_menu, 

MENU_NOTIFY_PROC, menu_return_item, 

0 ); " 

V_> 


Example 1: 



70 See Chapter 6, Handling Input , for a discussion of event procedures. 

71 The value of menu items not created with MENU_STRINGS defaults to zero. You can explicitly specify 
the values for menu items via the attributes MENU_IMAGE_ITEM, MENU_STRING_ITE M, or MENU_VALUE. 

72 Notify procedures are covered in detail in Section 12.7, Callback Procedures. 
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Example 2: It’s easy to build up more complex menus out of simple ones. The next example 

creates a menu with two items, ‘Bold’ and ‘Italic’, each of which shares the on- 
off menu from the previous example as a pull-right: 


r 

menu = menu_create (MENU__ITEM, 




MENU_STRING, 

"Bold", 



MENU PULLRIGHT, 

on_of f_menu. 



0, 




MENU_ITEM, 




MENU_STRING f 

"Italic", 



MENU PULLRIGHT, 

on_off_menu, 



0, 




0), 



< 





The most flexible way to create a menu item in-line in a menu_create () call 
is by using MENU_ITEM. In contrast to MENU_STRINGS, which allows you to 
specify only the display strings of the items, MENU_ITEM takes as its value a 
null-terminated attribute list which may contain any attributes applying to menu 
items . 73 

The value of MENU_STRING is the item’s display string; the value of 
menu_PULLRIGHT is the handle of the item’s pull-right menu. (Note that you 
must already have created the menu before giving it as the value for 
MENU_PULLRIGHT.) 


Example 3: The menu package can accommodate images as well as strings. The example 

below creates a menu with a single item labelled ‘tools’. When the user pulls 
right, he brings up a menu showing the icons of three SunView tools — 
defaultsedit,iconedit, and fontedit. 


73 For a complete list of such attributes, see the Menu Item Attributes table in in Chapter 19, SunView 


Interface Summary. 
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In order to pass an image into the menu package you need a pointer to a memory 
pixrect containing the image. One common way to create such an image is by 
first using iconedit to create the image and save it to a file. You then include the 
file in your program, and use the mpr_stat ic () macro to create a memory 
pixrect: 

-— > 

static short d_defaults[] = { 

♦include <images/defaultsedit.icon> 

}; 

mpr_s t at ic (default s_pr, 64, 64, 1, d__defaults); 

static short d_icon[] = { 

♦include Cimages/iconedit.icon> 

}; 

mpr_static (icon_pr, 64, 64, 1, d_icon); 

static short d_font[] = { 

♦include <images/fontedit.icon> 

}; 

mpr_static(font^pr, 64, 64, 1, d_font); 

tool_menu = menu_create(MENU_IMAGES, 

&default s_j?r, &icon_pr, &font_pr, 0, 

0 ); 

menu = menu_create (MENU_ITEM, 

MENU_STRING, "tools”, 

MENU_PULLRIGHT, tool_menu, 

0 , 

0 ); 

s_ ) 


The attribute MENU_IMAGES is analogous to MENU_STRINGS. It takes a list of 
images (pointers to pixrects) and creates a menu item for each image. 
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12.2. Components of 

Menus & Menu Items 

Menus 

Visual Components 

Generate Procedures 

Notify Procedures 

Client Data 

Menu Items 

CAUTION 

Menu Items 

Representation on the Screen 


This section gives an overview of the most important components of menus and 
menu items. Detailed discussion and examples follow later in the chapter. 


The text for a menu is rendered in the menu’s font, which you may specify via 
MENU_FONT. A menu has a shadow, you can specify the shadow’s pattern, or 
disable the shadow entirely, via MENU_SHADOW. You can give a title to a menu 
via MENU_TITLE_IMAGE or MENU_TITLE_ITEM . 74 By default, a menu’s 
items are laid out vertically; you can specify that the items be laid out horizon¬ 
tally or in a two-dimensional matrix via MENU_NCOLS and MENU_NROWS. 

You may specify a generate procedure for a menu, which will be called just 
before the menu is displayed. This allows you to implement context-sensitive 
menus by dynamically modifying the menu, or even replacing it entirely. 75 

The menu’s notify procedure is called after the user makes a selection. By using 
a notify procedure, you can perform an action or alter the resultor alter the result 
to be returned by menu_show () 76 . 

The menu’s client data field, accessible through MENU_CLIENT_DATA, is 
reserved for the application’s use. You can use this attribute to associate a 
unique identifier, or a pointer to a private structure, with a menu. 

A menu contains an array of items. To retrieve a menu’s nth item, use 
MENU_NTH_ITEM. To retrieve the total number of items in a menu use 
MENU_NITEMS. 

The same menu item can appear in more than one menu. 

Menu items, unlike panel items, are counted starting with one. 


A menu item is either displayed as a string or an image (a pointer to a pixrect). If 
the item has another menu associated with it using the MENU_PULLRIGHT attri¬ 
bute, then it is a pull-right item. 


74 The title is nothing more than an inverted, non-selectable item. It does not automatically appear at the top 
of the menu — it is your responsibility to position it where you want it. 

75 See example 8 in Section 12.7, Callback Procedures , later in the chapter. 

76 Notify procedures are discussed in detail in Section 12.7, Callback Procedures. 
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Item Values 


Item Generate Procedures 


Item Action Procedures 


Client Data 


Each menu item has a value. By default an item’s value is the initial ordinal 
position of the item if it was created with MENU_STRINGS; otherwise the 
default value is zero. You can set an item’s value explicitly when you create the 
item with MENU_STRING_ITEM or MENU_IMAGE_ITEM. You can also expli¬ 
citly set an item’s value with MENU_VALUE. However, if an item is a pull-right, 
then its MENU_VALUE is the value of its pull-right menu. This means that only 
“leaf’ menu items without submenus have a true value. 

As mentioned in Section 12.1, Basic Menu Usage, menu_show () by default 
returns the value of the item the user has selected. Since menu items are counted 
starting from one, a return value of zero from menu_show () would represent 
the null selection. 77 However, you may explicitly set the value of a menu item to 
zero. If you do, then a return value of zero could represent either a legal value 
for the selected item or an error. To tell whether or not the result was valid, call 
menu_get () with the boolean MENU_VALID_RESULT. A return value of 
TRUE means that the result was valid; FALSE means that the value is invalid. 

As with the menu as a whole, you may specify a generate procedure for each 
menu item, to be called just before the item is displayed. 

The action procedure of a menu item is analogous to the notify procedure of a 
menu. This is your chance to do something immediately based on the user’s 
selection. 

Menu notify procedures and item action procedures differ in when they are 
called. If the user chooses an item in a pull-right menu, the notify procedures (if 
any) for the menus higher up in the chain leading to the pull-right will be called, 
whereas the action procedures (if any) for the chosen menu item and menu items 
under it (“to its right”) will be called. 78 

Each menu item has a client data field, accessible through 
MENU_CLIENT_DATA, which is reserved for the application’s use. You can use 
this attribute to associate a unique identifier, or a pointer to a private structure, 
with each menu item. 


77 This is why menu items are counted starting with one, rather than zero: so that a zero return value would 
represent the null selection whether the menu show () was returning the value of the selected item or the item 
itself. 

78 Action procedures are discussed in detail in Section 12.7, Callback Procedures. 
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Item Margins The diagram below illustrates the layout of a menu item: 

Figure 12-1 Layout of a Menu Item 
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arrow 
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menu_margin represents the margin, in pixels, around an item in a menu. Its 
default value is 1. 

You can set an individual item’s margin by setting the menu item. To set the 
margins for all items in a menu, set the menu’s margin. 

You can adjust the horizontal placement of text in menu items with 
MENU_LEFT_MARGIN and MENU_RIGHT_MARGIN . 79 

As with MENU_MARGIN , the left and right margins can be set either for an indi¬ 
vidual menu item or for the menu itself, in which case the settings will apply to 
all the items in the menu. (The attributes MENU_FONT and MENU_BOXED also 
work this way.) 


12.3. Examples 

Example 4: 



Our next example will show several variations on a simple menu that could be 
used for selecting font point sizes. The default form is shown to the left. 

You could create the items with MENU_STRINGS, as in the previous example. 
Alternately, you could create the menu with no items, then use menu_set () to 
append the items to the menu: 80 



79 The placement of images is currently not affected by the settings of the left and right margins. 

80 Note that using MENU STRING ITEM with menu set () has the effect of an implicit append. Several 
attributes are provided to explicitly add items to a menu — see Table 12-1, Attributes to Add Pre-Existing Menu 
Items , later in this section. 
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MENU_STRING_ITEM takes as values the item’s string and its value. 

Now let’s see some of the ways in which the appearance of this basic menu can 
be altered. 

By setting MENU_INACTIVE to TRUE for an item, you can “gray out” the item 
to indicate to the user that it is not currently selectable. 


The menu to the left could be produced by: 


f 

for 

(i = 

4; i <= 6; i++) { 

A 


) 

item 

menu_ 

= menu_get (m, MENU_NTH_ITEM, i) ; 
set(item, MENU_INACTIVE, TRUE, 0); 


s, 



J 


Inactive items do not invert when the cursor passes over them. 


The call menu_set(m, MENU_BOXED, TRUE, 0) will cause a single¬ 
pixel box to be drawn around each item. With the default margin of 1 pixel, this 
will result in two-pixel lines between each item. 


Increasing the margin, by setting MENU_MARGIN to 5, will cause the items to 
spread out evenly, and the boxes to appear as individual boxes rather than divid¬ 
ing lines. 


You can control the layout of the items within a menu with the attributes 
MENU_NCOLS and MENU_NROWS. Suppose you wanted the menu to be laid out 
horizontally instead of vertically: 



All you need do is specify at create time that the menu will have 6 columns with 
a call such as menu_set (m, MENU_NCOLS, 6, 0). 



You can use MENU_NCOLS or MENU_NROWS to create two-dimensional menus, 
as well. The call menu_set (m, MENU_NCOLS, 3, 0) will cause the 
menu package to begin a second row after the first three columns have been filled 
with items: 
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The previous example specified that the menu have 3 columns. Specifying that it 
have 2 rows via MENU_NROWS would have the same effect. Items are laid out 
from upper left to lower right, in “reading order,” regardless of how the layout is 
specified. 


8 

18 

12 

14 

16 

18 1 


The only time you need to specify both the number of rows and the number of 
columns is when you want to fix the size of the menu, regardless of how many 
items it contains. Setting MENU_NCOLS to 3 and MENU_NROWS to 3 would pro¬ 
duce: 

If both dimensions of the menu are fixed and more items are given than will fit, 
the excess items will not appear. 


8 

18 

12 

14 

16 

18 


You can remove the menu’s shadow by setting MENU_SHADOW to null: 

The menu package provides three predefined pixrects for the menu shadow. The 
call menu_set (m, MENU_SHADOW, &menu_gray25_pr) produces the 
25 percent gray pattern shown on first menu below. Note that these are pixrects, 
not pixrect pointers. The other two patterns are produced by using 
menu_gray50_pr and menu_gray75_pr: 



8 

18 

12 

14 

16 

18 





Example 5: Let’s take the size menu from the previous example and use it to create the more 

complex menu shown below, which the user could use to select both a font fam¬ 
ily and a point size within the family. This illustrates the multiple usage of a sin¬ 
gle menu. Pulling right over any of the items in the family menu will bring up 
the menu for selecting point size, as shown on the left. 
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By using MENU_ITEM, we can give each item in the font family menu its string, 
the font in which to render the string, and the size menu as a pull-right: 


f — 






\ 


family__menu = menu create ( 






MENU_ITEM, 







MENU_STRING, 

"Courier”, 

MENU 

_FONT, 

cour. 



MENU_PULLRIGHT, 

size_menu. 

0 , 





MENU_ITEM, 







MENU_STRING, 

"Serif ", 

MENU 

FONT f 

serif. 



MENU_PULLRIGHT, 

size_menu f 

0 , 





MENU_ITEM, 







MENU_STRING, 

"aplAPLGIJ", 

MENU 

FONT, 

apl. 



MENU_PULLRIGHT, 

size_menu f 

0 , 





MENU_ITEM, 







MENU_STRING, 

"CMR ", 

MENU 

FONT, 

cmr. 



MENU_PULLRIGHT f 

size_menu, 

0 , 





MENU_ITEM f 







MENU_STRING f 

"Screen" f 

MENU 

_FONT, 

screen. 



MENU__PULLRI GHT , 

size_menu f 

0 , 





0); 






s_ 






_> 


Courier 

=» | 


Serif 

=> 1 



1 8 


CUR 

10 1 

Screen 

12 


14 


16 


18 


Suppose the font family menu had already been created, and we wanted to add 
the size menu as a pull-right to each item of the existing menu. We could do this 
using the attributes MENU_NITEMS and MENU_NTH_ITEM. The loop below 
iterates over each item in the menu, retrieving the item’s handle and setting the 
pull-right for the item: 


-- 

for (i = (int) menu_get (family_menu, MENU__NITEMS) ; i > 0; —i) 
menu_set (menu_get (family_menu, MENU_NTH_ITEM, i) , 
MENU_PULLRIGHT, size_menu, 0) ; 

v_/ 
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Example 6: 



You can insert new items into an existing menu with MENU_INSERT. For 
example, suppose you want to insert blank lines into the font family menu, to 
indicate grouping: 

You can do this by inserting non-selectable items into the menu: 

-'l 

menu_set (family_menu, 

MENUJENSERT, 

2 , 

menu_create__item (MENU_STRING, " " f 

MENU__FEEDBACK , FALSE, 

0 ), " 

0 ); 

menu_set (family_menu, 

MENUHINSERT, 

5, 

menu_get (family_menu f MENU_NTH_ITEM, 3) , 

0 ); 

S- ) 

MENU_INSERT takes two values: the number of the item to insert after, and the 
new item to insert. Disabling MENU_FEEDBACK makes the item non-selectable. 

The above example uses menu_create_item () to explicitly create the item 
to be inserted. Usually menu items are created implicitly, using the attributes 
described in Table 12-2, Menu. Item Creation Attributes, in the next section. 


NOTE menu_create_item () does not set the MENU_RELEASE attribute by 

default, so that the resulting item will not be automatically destroyed when its 
parent menu is destroyed. This is in contrast to implicitly created menu items — 
see Section 12.5, Destroying Menus. 
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In addition to MENU_INSERT, there are several other attributes you can use to 
add pre-existing menu items to a menu. 81 They are summarized in the following 
table. 

Table 12-1 Attributes to Add Pre-Existing Menu Items 


Attribute 

Value Type 

Description 

MENU_AP P END__ITEM 

Menu_item 

Append item to end of menu. 

MENU_INSERT 

int, Menu_item 

Insert new item after nth item 
(use n=0 to prepend). 

MENU_INSERT_ITEM 

Menu_item(old), 



Menu_item (new) 

Insert new item after old item. 

MENU__RE P LACE 

int, Menu_item 

Replace nth item with specified item. 

MENU_REP LACE_ITEM 

Menu_item(old), 



Menu_item (new) 

Replace old item with new item 
in the menu (old item is not replaced 
in any other menus it may appear in). 


81 To delete items from a menu, use MENU_REMOVE or MENU_REMOVE_ITEM, described in the Menu 
Attributes table in in Chapter 19, SunView Interface Summary. 
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Example 7: 


Frame =» 
Fami ly =» 
Size =*► 


Bold 


On 


Ital 


For the next example we will attach the on-off, family and size menus of the pre¬ 
vious examples as pull-rights to a higher-level menu for selecting fonts: 


font_menu * menu_create( 

MENU_P ULLRIGHT_ITEM, 
MENU_P ULLRI GHT__I TEM, 
MENU_P ULLRIGHT_ITEM, 
MENUJPULLRI GHT_I TEM, 
MENU_P ULLRI GHT_I TEM, 
0 ); 


"Frame", 
"Family", 
"Size", 
"Bold", 
"Italic", 


frame__menu f 
family__menu, 
size__menu, 
on_of f_menu, 
on_of f_menu. 


MENU_PULLRIGHT_ITEM takes a string and a menu as values. It creates an 
item represented by the string and with the menu as a pull-right. 


Note that on_of f menu is used as a pull-right for both the bold and the italic 
menu items, and that the size_menu appears both as a pull-right from main 
level f ont_menu and from each item in f amily_menu. This demonstrates 
that a menu may have more than one parent. However, recursive menus are not 
allowed — if Ml is a parent of M2, M2 (or any of its children) may not have Ml 
as a child. Displaying such a recursive menu will probably result in a segmenta¬ 
tion fault 


The ‘Frame’ item takes as its pull-right the menu which has been retrieved from 
the frame using WIN_MENU. 

The program fontjnenu, printed in Appendix A, Example Programs, builds 
further on the above examples. 
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12.4. Item Creation The attribute MENU_ITEM, introduced in Example 2, suffices to create any type 

Attributes of menu item. However, several attributes are provided for convenience as a 

shorthand way to create items with common attributes. These attributes, along 
with the types of values they take and the type of item they create, are summar¬ 
ized in the following table: 

Table 12-2 Menu Item Creation Attributes 


Attribute 

Value Type 

Type of Item Created 

MENU_ACT ION_IMAGE 

image, action proc 

Image item w/action proc. 

MENU_AC TION_ITEM 

char *, action proc 

String item w/action proc. 

MENU_GEN_PULLRIGHT_IMAGE 

Pixrect *, proc 

Image item with 
generate proc for pull-right. 

MENU_GEN_PULLRIGHT_ITEM 

char *, proc 

String item with 
generate proc for pull-right. 

MENU_IMAGE_ITEM 

Pixrect *, value 

Image item w/value. 

MENU_IMAGES 

list of Pixrect * 

Multiple image items. 

MENU_PULLRIGHT_IMAGE 

Pixrect *, Menu 

Image item w/pull-right. 

MENU_PULLRIGHT_ITEM 

char *, Menu 

String item w/pull-right. 

MENU_STRING_ITEM 

char *, value 

String item w/value. 

MENU_STRINGS 

list of char * 

Multiple string items. 


We could now create the menu in Example 2 more compactly by using 
MENU_PULLRIGHT_ITEM instead of MENU_ITEM: 

' ---v 

m - menu_create(MENU_PULLRIGHT_ITEM, "Bold", on_off_menu, 

MENU_PULLRIGHT_ITEM, "Italic", on_off_menu, 

0 ), 

--- , 
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12.5. Destroying Menus Both menus and menu items are destroyed with the function: 

void 

menu_destroy(menu_object) 

<Menu or Menu item> menu_ob ject; 


CAUTION Watch out for dangling pointers when using a menu item in multiple menus. The 

attribute MENU_RELEASE (which takes no value) controls whether or not a 
menu item is automatically destroyed when its parent menu is destroyed. 
MENU_RELEASE is set to TRUE by default for menu items created in-line via 
the menu item creation attributes. This can lead to dangling pointers, if the same 
menu item appears multiple times, because calling menu_destroy () can lead 
to items being destroyed multiple times. This warning also applies to pull-rights 
which are used multiple times. To prevent this error, remove multiple 
occurrences of an item or pull-right before destroying a menu. 

Calling menu_destroy_with j>roc () instead of menu_destroy () 
when you want to destroy a menu lets you specify a procedure to be called as the 
menu or menu item is destroyed, lets you specify a procedure to be called every 
time a particular menu or menu item is about to be destroyed: 

void 

menu_destroy_with_proc (menu_ob ject, destroy_j?roc) 

<Menu or Menu_item> menu_ob ject; 
void (*destroy_proc) (); 

Your destroy procedure should be of the form: 

void 

destroy__proc (menu_ob ject f type) 

<Menu orMenu_item> menu_object; 

Menu_attribute type; 

For menus, menu_ob j ect is the menu and the type parameter is 
MENU_MENU; for menu items, menu_ob ject is the item and the type param¬ 
eter is MENU ITEM. 
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12.6. Searching for a Menu 
Item 


The function menu__f ind () lets you search through a menu (and its children) 
to find a menu item meeting certain criteria: 

Menu_item 

menu__f ind (menu, attributes) ; 


Menu 


menu; 


<attribute-list> attributes; 

For example, the following call searches for the menu item whose string was 
“Load New File”, menu find() will return itNULLif 


r 


whose string was "Load New File": 


v 




By default, menu_f ind () uses a “deferred” search — searching all the items 
in a menu before descending into any pull-rights which may be present. By set¬ 
ting MENU_DESCEND_FIRST (which takes no value), you can force a depth- 
first search. 

If multiple attributes are given, menu__f ind () will find the first item matching 
all the attributes. 

The following attributes are recognized by menu_f ind (): 


Table 12-3 Menu Attributes Recognized by menu_f ind () 


MENU_ACTION 
MENU_CLIENT_DATA 
MENU_FEEDBACK 
MENU_FONT 
MENU__GEN__P ROC 
MENU_GEN_PULLRIGHT 
MENU_IMAGE 
MENU INACTIVE 


MENU_STRING 
MENU VALUE 


MENU INVERT 


MENU LEFT MARGIN 


MENU_MARGIN 
MENU PARENT 


MENUJPULLRIGHT 
MENU RIGHT MARGIN 
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12.7. Callback Procedures When you call menu_show (), the menu package displays the menu, gets a 

selection from the user, and undisplays the menu. The menu package allows you 
to specify callback procedures which will be called at various points during the 
invocation of the menu. These let you create and modify menus or respond to 
the user’s actions, on the fly, at the time the user brings up the menu. There are 
three types of callback procedures: generate procedures (so named because they 
are called before the menu or item is displayed, allowing the application to gen¬ 
erate or modify the menu on the fly), notify procedures (for menus) and action 
procedures (for menu items) which are called after the user has made a selection. 

Flow of Control in The callback mechanism gives you a great deal of flexibility in creating, combin- 

menu_show () ing and modifying menus and menu items. This flexibility comes at the price of 

some complexity, however. To take advantage of it, it is necessary to understand 
when the callback procedures are called after you invoke menu_show (). 

For purposes of explanation, the diagrams below divide the process of displaying 
a menu and getting the user’s selection into two stages, the display stage and the 
notification stage. 
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Figure 12-2 Display Stage of Menu Processing 


Start menu show () 



To Notification Stage 
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Figure 12-3 Notification Stage of Menu Processing 


From Display Stage 



Return from menu_show () 


Generate Procedures The first argument to a generate procedure is either a menu or menu item depend¬ 

ing on whether it’s a MENU_GEN_PROC or a MENU_GEN_PROC_lTEM. Also 
passed in is an operation indicating at which point in the processing of the menu 
the generate procedure is being called. The operation parameter is of type 
Menu_generate, and may be MENU_DISPLAY, MENU_DISPLAY_DONE, 
MENU_NOTIFY or MENU_NOTIFY_DONE . 82 

NOTE The menu package uses the fullscreen access mechanism when displaying the 

menu. Writing to the screen while under fullscreen access will probably cause 
your program to deadlock, so your generate procedure should not access the 
screen when called with an operation o/MENU_DISPLAY or 
MENU DISPLAY DONE. 


82 For a detailed explanation of when the generate procedures are called in relation to the other callback 
procedures, see the diagrams in the next subsection. Flow of Control in menu_show (). 
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There are three types of generate procedures — menu item generate procedures, 
menu generate procedures, and pull-right generate procedures. A description 
and example of each is given below. 

Menu Item Generate Procedure A generate procedure attached to a menu item has the form: 

Menu_item 

menu_item_gen_proc(item, operation) 

Menu_item item; 

Menu_generate operation; 

You can specify a menu item generate procedure via MENU_GEN_PROC. 


Example 8: 


The most common use of menu item generate procedures is to modify the item’s 
display string. The program listed below registers a generate procedure, 
toggle_proc (). If it has been called from the menu_display stage of 
processing, it toggles the text of the ‘Redisplay’ item on the frame menu. 


#include <suntool/sunview.h> 

Menu_item togglejproc(); 
int toggle = 0; 

main () 

{ 

Window frame = window_create(NULL, FRAME, 0) ; 
Menu menu = window_get(frame, WIN_MENU); 

Menu_item item = menu__find (menu, 

MENU_STRING, "Redisplay", 0); 

menu_set(item , MENU_GEN_PROC, toggle_proc, 0); 
window_main_loop (frame) ; 

} 

Menu__item 

toggle_j?roc(mi, op) 

Menu__item mi; 

Menu_generate op; 


{ 


switch (op) { 

case MENU_DISPLAY: 
if (toggle) { 

menu_set(mi, 

MENU__STRING, "Redisplay has been seen", 

0 ); ’ 

} else { 

menu__set (mi, 

MENU_STRING, "Redisplay", 

0 ); " 

} 

toggle = !toggle; 
break; 

case MENU_DISPLAY_DONE: 
case MENU NOTIFY: 
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Menu Generate Procedure 


Example 9: 


r 

case MENU_NOTIFY_DONE: 
break; 

} 

return mi; /* item handle always returned */ 


} 

_/ 



The ‘Zoom’/‘Unzoom’ item in the SunView frame menu also uses this technique 
to toggle its display string. Note that since this item knows how to modify itself, 
you could put it in other menus and get the same behavior. A generate procedure 
for a menu item allows the application to be called even when it has no 
knowledge of or control over the call to menu_show (). 

A generate procedure attached to a menu has the form: 

Menu 

menu_gen_jproc (m, operation) 

Menu m; 

Menu_generate operation; 

You can specify a menu generate procedure via the attribute MENU_GEN_PROC. 

We will take as an example a menu allowing the user to list different groups of 
files. When the user makes a selection, we generate a menu containing the 
correct set of files: 


List dot files => | 

List bin dir 

clock | 
shelltool I 
iconedit 

List all files 



The relevant functions are listed on the next page. The first, 
initialize_menu (), creates the three menu items, giving each of them the 
generate procedure list_f iles (), and a unique identifier as 
MENU_C LIENT_DATA. 

Remember that list_f iles () is called in four different situations by 
menu_show () : 83 

□ When the operation is MENU_D ISP LAY, the pull-right is being asked to 
display its menu, so list_f iles () calls the function 
get_f ile_names () (not shown) to get the appropriate list of file names. 


83 See the diagrams in the earlier subsection. Flow of Control in menu show (). 
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and adds each name in the list to the menu. 

□ When list_files () is called with operation set to 

MENU_D I SPLAY_DONE, the menu of generated file names is no longer 
being displayed. list_files() cleans up by destroying the old menu of 
file names, replacing it with a fresh menu with the same generate procedure. 
It returns the handle of this new menu. 

o Whenlist_files () is called with an operation of MENU_N0TIFY 
or MENU NOTIFY DONE, the menu is returned unaltered. 


#define DOT 0 
#define BIN 1 
#define ALL 2 

static void 
initialize_menu(menu) 

Menu menu; 

{ 

m = menu_create (MENU_GEN_PROC, list_files f 

MENU_CLIENT_DATA, DOT, 

0 ); " 

menu_set (menu, 

MENU_PULLRIGHT_ITEM, "List dot files", m, 

0 ); " 

m = menu_create (MENU_GEN__PROC, list__files, 

ME NU_CLIENT_DATA, BIN, 

0 ); " 

menu_set (menu, 

MENU__PULLRIGHT_ITEM, "List bin dir", m, 

0 ); “ 

m = menu_create (MENU_GEN_PROC, list_files, 

MENU_CLIENT_DATA, ALL, 

0 ); " 

menu__set (menu, 

MENU_PULLRIGHT_ITEM, "List all files", m, 

0 ); " 


static Menu 

list_files(m, operation) 

Menu m; 

Menu_generate operation; 

{ 

char **list; 
int directory; 

int i = 0; 

switch (operation) { 
case MENU_DISPLAY: 

directory = (int)menu_get(m, MENU_CLIENT_DATA) ; 
list = get_file__names (directory); 
while (*list) 
menu_set (m, 

MENU_STRING_ITEM, *list++, i++, 

0 ); 

break; 
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case MENU_DISPLAY_DONE: 

/* 

* Destroy old menu and all its entries. 

* Replace it with a new menu. 

*/ 

directory = (int) menu__get (m, MENU_CLIENT_DATA) ; 
menu_destroy (m) ; 

m = menu_create (MENU_GEN_PR0C, list_files, 
MENU_CLIENT_DATA, directory, 

0 ); " 

break; 

case MENU__NOTIFY: 
case MENU_NOTIFY_DONE: 
break; 


/* The current or newly-created menu is returned */ 
return m; 


Pull-right Generate Procedure You can postpone the generation of a pull-right menu until the user actually pulls 

right by specifying a pull-right generate procedure. A pull-right generate pro¬ 
cedure has the form: 

Menu 

pullright_gen_j?roc (mi, operation) 

Menu__item mi; 

Menu_generate operation; 

Note that the pull-right generate procedure is passed the item, and returns the 
menu to be displayed. 

You can specify a menu item’s pull-right generate procedure with a call such as 

/— - — > 

menu_set (menu__item, MENU_GEN_PULLRIGHT, my__pullright__gen f 0) ; 

---' 

Alternatively, you can use the attributes MENU_GEN_PULLRIGHT_IMAGE or 
MENU_GEN_PULLRIGHT_ITEM to give a menu both an item and the item’s 
generate procedure. 

If you want to get the existing menu for an item which has a pull-right generate 

procedure, retrieve the value of the item, as in: 

--— > 

menu = menu_get (item, MENU_VALUE) ; 
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Notify/Action Procedures 



When the user selects a menu item by releasing the mouse button, the menu 
package calls back to any notify procedures or action procedures you have 
specified. Notify procedures and action procedures have the form: 

caddr_t 

notify_proc(m, mi) 

Menu m; 

Menu_item mi; 

The most common usage is to have action procedures for the items at the leaf 
nodes of the walking menu. The general mechanism described below is provided 
to allow your procedures to be called for non-leaf nodes as well. 

Imagine a chain of menus expanded out. Lookup of the notify/action procedures 
starts with the “oldest” menu, the one passed to menu_show (). If it has a 
notify procedure, that notify procedure is called, otherwise the default notify pro¬ 
cedure, menu_return_value (), is called. Likewise, for each menu down 
the chain, until the menu with the selected item is reached. If the selected item 
has an action procedure, that action procedure is called. If the selected item is 
not on a leaf node, then action procedures for any items farther down the chain 
are also called. 

Let’s see what happens in the example to the left (assume that ‘On’ is the default 
item for the first menu): 

If ‘Italic’ was selected: 

□ no callback to the first menu’s notify procedure since an item in it is 
selected, 

□ callback to the action procedure for the ‘Italic’ item, 

□ no callback to the second menu’s notify procedure since it is further down 
the chain than the selected item, 

□ callback to the action procedure for the ‘On’ item. 


If ‘Off was selected: 

□ callback to the notify procedure for the first menu, since an item in a menu 
further down the chain than it is selected, 

□ no callback to the action procedure for the ‘Italic’ item, since it is above the 
selected item in the chain, 

□ no callback to the second menu’s notify procedure since an item in it is 
selected, 

□ callback to the action procedure for the ‘Off item. 

NOTE If you specify a notify procedure, it is your responsibility to propagate the 

notification to any menus further down in the chain. You can do this by calling 
menu_get (mi, MENU_VALUE) from your notify procedure. This gets the 
value of the selected menu item, and since the value of a pull-right item is the 
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value of its pull-right menu, this will make notify/action procedures further down 
the chain get called. 


12.8. Interaction with Walking Menus for frames and tty subwindows can be customized. 84 All menu 

Previously Defined items in these menus are “position-independent” — in other words the menus do 

SunView Menus not count on a given item having a certain position or being located in a particu¬ 

lar menu. This makes it possible for you to safely add new items (including 
pull-right submenus) to an existing menu. 

NOTE You should not use the client data field of items created by SunView packages, 
because the packages have pre-empted it for their own use. 

Using an Existing Menu as a The program fontjnenu, listed in Appendix A, shows how you can replace an 

Pull-right existing menu with your own menu which has the original menu as a pull-right. 

Making use of several of the examples given earlier in the chapter, it creates a 
font menu which allows the user to select the font family, point size, and whether 
or not the font is bold or italic. Meanwhile, the first item, labelled ‘Frame’, 
brings up the original frame menu: 


Frame 

Close | 

Family 

Hove => | 

Size 

Resize => | 

Bold 

Expose 

Italic 

Hi de 


Redisplay 1 


Quit 


84 Remember that in order to have these packages use walking menus the user must have enabled the 
Walking Menus option in SunView category of defaultsedit(l); in SunOS Release 4.0, this is the default. 
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12.9. Initial and Default Two special menu items are the default item (MENU_DEFAULT_ITEM) and the 

Selections selected item (MENU_SELECTED_ITEM). The default item is simply a dis¬ 

tinguished item. The selected item is the item which was last selected. 

Two attributes are provided to control the behavior of a menu in regard to its ini¬ 
tial selection. If MENU_INITIAL_SELECTION_SELECTED is TRUE, the 
menu comes up with its initial selection selected — that is the selection is 
inverted and the cursor is positioned over it. If FALSE, the menu comes up with 
the cursor “standing off’ to the left and no selection highlighted. If 
MENU_INITlAL_SELECTION_EXPANDED is TRUE, when the menu comes 
up, it automatically expands any pull-rights which are necessary to bring the ini¬ 
tial selection up on the screen. 

Each menu also has an initial selection (MENU_INITIAL_SELECTI0N) and a 
default selection. (MENU_DEFAULT_SELECTION). 

The distinction between the initial selection and the default selection is subtle. 
Suppose MENU_INITIAL_SELECTI0N_EXPANDED was TRUE, and the ini¬ 
tial selection was an item in a pull-right. When the menu comes up, it will be 
expanded to show the initial item as selected. However, if the user moves the 
cursor to the left, backing out of the pull-right, and then moves back to the right, 
bringing the pull-right up again, the item selected will be the default selection 
rather than the initial selection. 

When the user selects a pull-right item without bringing up the associated menu, 
it is as if he had brought the pull-right up and selected the default item. 

You can set the initial selection and the default selection independently — either 
can be set to the default item or the selected item. 
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12.10. User Customizable The user can specify the values of certain menu attributes in the Menu category 

Attributes of default sedit (1). When a menu is created, for attributes not explicitly 

specified by the application program, the menu package retrieves the values set 
by the user from the defaults database maintained by default sedit. This 
allows the user the ability to tailor, to some extent, the appearance and behavior 
of menus across different applications. For example, he may want to change the 
type of shadow, or expand the menu margin, and so on. 

The attributes under default sedit control are listed in the following table. 


Table 12-4 User Customizable Menu Attributes 


Attribute 

Default 

Description 

MENU_BOXED 

FALSE 

If TRUE, a single-pixel box will be 
drawn around each menu item. 

MENU_DEFAULT_SELECTION 

MENU_DEFAULT 

MENU_SELECTED or MENU_DEFAULT. 

MENU_FONT 

screen.b.12 

Menu’s font. 

MENU_INITIAL_SELECTION 

MENU_DEFAULT 

MENU_SELECTED or MENU_DEFAULT. 

MENU_INITIAL_SELECTION_SELECTED 

FALSE 

If true, menu comes up with its initial 
selection highlighted. If FALSE, menu comes 
up with the cursor "standing off to the left. 

MENU_INITIAL_SELECTION_EXPANDED 

TRUE 

If true, when the menu pops up, it auto¬ 
matically expands to select the initial selection. 

MENU_JUMP_AFTER_NO_SELECTION 

FALSE 

If true, cursor jumps back to its 
original position after no selection made. 

ME NU_JUMP_AF T E R_S ELECTION 

FALSE 

If TRUE, cursor jumps back to its 
original position after selection made. 

MENU_MARGIN 

1 

The margin around each item. 

MENU_LEFT_MARGIN 

16 

For each string item, margin in addition to 
MENU_MARG IN on left 
between menu’s border and text. 

MENU_PULLRIGHT_DELTA 

9999 

# of pixels the user must move the cursor to 
the right to cause a pull-right menu to pop up. 

MENU_RIGHT_MARGIN 

6 

For each string item, margin in addition to 
MENU_MARGIN on right 
between menu’s border and text. 

MENU SHADOW 

50% grey 

Pattern for menu’s shadow. 
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Cursors 


This chapter describes how to create and manipulate cursors , 85 A cursor is an 
image that tracks the mouse on the display. Each window in SunView has its 
own cursor, which you can change with the cursor package. 

If it is installed on your system, you can run the demo 

/usr/demo/cur sor_demo to see the effects of various cursor attributes. 

The source for this is in 

/usr/src/share/sun/suntool/cursor_demo.c. 

Header Files The definitions necessary to use cursors are found in the include file 

<sunwindow/win_cursor . h>, which is included by default when you 
include the file <suntool/sunview.h>. 

Summary Listing and Tables To give you a feeling for what you can do with cursors, the following page con¬ 
tains a list of the available cursor attributes and functions. Many of these are dis¬ 
cussed in the rest of this chapter and elsewhere (use the Index to check). All are 
briefly described with their arguments in the cursor summary tables in Chapter 
19, SunView Interface Summary: 

□ the Cursor Attributes table begins on page 321; 

a the Cursor Functions table begins on page 323. 


85 The cursor is called the “pointer” in user-level documentation. 
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Cursor Attributes 

CURSOR CROSSHAIR_BORDER_GRAVITY 

CURSOR_OP 

CURSOR CROSSHAIR_COLOR 

CURSOR_SHOW_CROSSHAIRS 

CURSOR_CROSSHAIR_GAP 

CURSOR_SHOW_CURSOR 

CURSOR_CROSSHAIR_LENGTH 

CURSOR_SHOW_HORIZ_HAIR 

CURSOR_CROSSHAIR_OP 

CURSOR_SHOW_VERT_HAIR 

CURSOR_CROSSHAIR_THICKNESS 

CURSOR_VERT_HAIR_BORDER_GRAVITY 

CURS OR_FULLS CREEN 

CURSOR_VERT_HAIR_COLOR 

CURSOR_HORIZ_HAIR_BORDER_GRAVITY 

CURSOR_VERT_HAIR_GAP 

CURS OR_HORIZ_HAIR_COLOR 

CURSOR_VERT_HAIR_LENGTH 

CURSOR_HORIZ_HAIR_GAP 

CURSOR_VERT_HAIR_OP 

CURSOR_HORIZ_HAIR_LENGTH 

CURSOR_VERT_HAIR_THICKNESS 

CURSOR_HORIZ_HAIR_OP 

CURSOR_XHOT 

CURSOR_HORIZ_HAIR_THICKNESS 

CURSOR_YHOT 

CURSOR_IMAGE 



Cursor Functions 

cursor__copy (src_cursor) 
cursor_create(attributes) 
cursor_destroy(cursor) 

cursor_get(cursor, 
cursor_set (cursor. 

attribute) 

attributes) 
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13.1. Creating and 

Modifying Cursors 


13.2. Copying and 

Destroying Cursors 


Example 1: Creating a Window 
with a Custom Cursor 


The basic usage of the cursor package is to first create a cursor with 
cursor_create (), and then use this cursor as the value of the 
WlN_CURSOR attribute in your call to window_create (). 

Cursor 

cursor_create(attributes) 

<attribute-list> attributes; 

Once you have created a cursor, you can alter its attributes with 
cur sor__set () and read back its attributes with cursor_get (): 

void 

cursor_set(cursor, attributes) 

Cursor cursor; 

<attribute-list> attributes; 

caddr_t 

cursor__get (cursor, attribute) 

Cursor cursor; 

Cursor_attribute attribute; 

If you want to change the cursor of a window that has already been created, you 
can first get the cursor from the window using window_get () of 
WlN_CURSOR, then use cur sor_set () to change the cursor, and then use 
window_set () of WIN__CURSOR to re-attach the cursor to the window. 

A copy of an existing cursor can be made with cur sor_copy (): 

Cursor 

cursor_copy(src_cursor) 

Cursor src__cursor; 

A cursor can be destroyed and its resources freed with cur sor_destroy (): 
void 

cursor_destroy(cursor) 

Cursor cursor; 

A common use for cursors might be to create a canvas subwindow and have it 
use the cursor of your choice, rather than the default arrow cursor: 


13.1. Creating and 

Modifying Cursors 


13.2. Copying and 

Destroying Cursors 


Example 1: Creating a Window 
with a Custom Cursor 
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short my_pixrect_data[] = { 

#include "fdejromjconedit" 

}; 

mpr_static(my_pixrect, 16, 16, 1, my_j>ixrect__data) ; 
Canvas canvas; 


init__my_canvas () 

{ 

canvas = window_create(frame, CANVAS, 

WIN__CURSOR, cursor_create (CURSOR_IMAGE, 

0 ), 


} 


0 ); 


&my_pixrect. 


This example creates a cursor “on the fly” and passes it into the 
window_create () routine for use with the canvas. The attribute 
CURSOR_IMAGE is set to the a pointer to the pixrect we want to use (a diamond 
or bullseye, for example). All of the other cursor attributes default to the value 
shown in the attribute table. 


Example 2: Changing the Suppose you have already created a window and you want to change its cursor. 

Cursor of an Existing Window Let’s say you want to change the drawing op to P IX_SRC: 


r 

Cursor cursor; 


> 


cursor = window get (my_window, WIN__CURSOR) ; 



cursor^set (cursor, CURSOR__OP, PIX_ 

SRC, 0); 


\_ 

window set (my_window, WIN_CURSOR, 

cursor, 0); 

_/ 


CAUTION The cursor returned by window_get () is a pointer to a static cursor that 
is shared by all the windows in your application. So, for example, saving the 
cursor returned by window_get () and then making other window system calls 
might result in the saved cursor being overwritten. 86 

It is safe to get the cursor, modify it with cursor_set () and then put the cur¬ 
sor back. If there is any chance that the static cursor will be overwritten, you 
should use cursor_copy () to make a copy of the cursor, then use 
cursor_destroy () when you are done. 

13.3. Crosshairs Crosshairs are horizontal and vertical lines whose intersection tracks the location 

of the mouse. You can control the appearance of both the horizontal and vertical 
crosshairs along with the cursor image. For example, you can create a cursor that 
only shows the cursor image, or only the horizontal crosshair, or both the hor¬ 
izontal and vertical crosshairs and the cursor image. By default both the 
crosshairs are turned off and only the cursor image is displayed. 


86 Note that this would happen if one of the routines you call happens to call window get () of 
WIN CURSOR. 
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Example 3: Turning on the Suppose you have a canvas window in which you want to turn on both the hor- 

Crosshairs izontal and vertical crosshairs. This can be done by getting the cursor from the 

window and setting the CURSOR_SHOW_CROSSHAlRS attribute: 

( ----N 

Cursor cursor; 

cursor * window_get (my__canvas, WIN_CURSOR) ; 
cursor_set(cursor, CURSOR_SHOW_CROSSHAIRS, TRUE, 0); 
window_set (my_canvas, WIN_CURSOR, cursor, 0) ; 

V---_> 

When the crosshairs are turned on, they are displayed according to the current 
value of their other attributes (e.g. thickness and drawing op). 

This section describes some of the cursor attributes in more detail. Note that for 
the crosshair attributes, you can control the individual crosshairs as well as both 
crosshairs by using the appropriate attribute. For example, you can set the length 
for both crosshairs with CURSOR_CROSSHAIR_LENGTH or the length of only 
the horizontal crosshair with CURSOR_HORIZ_HAlR_LENGTH. 

cursorjmage The cursor image is the memory pixrect that is drawn on the screen as the mouse 

moves. Use the mpr_static () macro, as shown in Example 1, to create the 
memory pixrect. The image is represented as an array of 16 shorts, each of 
which represents a 16-pixel wide scan line. The scan lines are usually arranged 
in a single column, yielding a 16 x 16 pixel image. Other arrangements, such as 
32 pixels wide x 8 pixels deep, are also possible. The maximum size of a cursor 
in SunView 1 is 32 bytes; the minimum width is 16, the width of one scan line. 

cursorjchot and cursor.yhot The “hot spot” defined by ( CURSOR_XHOT, CURSOR_YHOT ) associates the 

cursor image, which has height and width, with the mouse position, which is a 
single point on the screen. The hot spot gives the mouse position an offset from 
the upper-left comer of the cursor image. For example, if the upper left comer of 
the cursor image is at location (50,40) and the cursor hot spot has been set to (8, 
8), the reported mouse position will be at (58,48). 

Most cursors have a hot spot whose position is obvious from the image shape: 
the tip of an arrow, the center of a bullseye, the center of a cross-hair. Cursors 
can also be used to give status feedback — an hourglass to indicate that the pro¬ 
gram is not responding to user input is a typical example. This type of cursor 
should have the hot spot located in the middle of its image so the user has a 
definite spot for pointing and does not have to guess where the hot spot is. 

cursor_op The value given for this attribute is the rasterop which will be used to paint the 

cursor. 87 PIx_SRC | PIX_DST is generally effective on light backgrounds — 
in text, for example — but invisible over solid black. PIx_S RC ~ Pix_DST 
is a reasonable compromise over many different backgrounds, although it does 
poorly over a gray pattern. 


13.4. Some Cursor 
Attributes 


87 Rasterops are described fully in the Pixrect Reference Manual. 
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CURSOR_FULLSCREEN 

The cursor crosshairs can be clipped to either the cursor’s window or the entire 
screen. If you want the crosshairs to extend past the edge of the window, set 
CURSOR_FULLSCREEN to TRUE. 

CURSOR_CROSSHAIR_LENGTH 

If you don’t want the crosshairs to cover the entire window (or screen), you can 
set the length of both crosshairs with CURSOR_CROSSHAlR_LENGTH. The 
value of this attribute is actually half the total crosshair length. For example, if 
you want the crosshairs to be 400 pixels wide and high, set the 

CURSOR CROSSHAlR_LENGTH to 200. You can restore the extend-to-edge 
length by giving a value of CURSOR_TO_EDGE for 

CURSOR CROSSHAIR LENGTH. 


cursor_crosshair_border_gravity If the crosshair border gravity is enabled, the crosshairs will "stick” to the edge of 


CURSOR_CROSSHAIR_GAP 

the window (or screen). This is only interesting if the 
CURSOR_CROSSHAIR_LENGTH is not set to CURSOR_TO_EDGE. With 
border gravity turned on, each half of each crosshair will be attached to the edge 
of the window. With the cursor image displayed, this feature might be useful to 
help the user line up the cursor to a grid drawn on the edges of the window. 

If you don’t want the halves of each crosshair to touch, you can set the 

CURSOR CROSSHAIR GAP to the half-length of space to leave between each 
crosshair half. If you set CURSOR_CROSSHAIR_GAP to CURSOR_TO_EDGE, 
the crosshairs will back off to the edge of the CURSOR_iMAGE rectangle. 
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Header Files 


Summary Listing and Tables 


14 

Icons 


An icon is a small (usually 64 by 64 pixel) picture representing a base frame in 
its closed state. The icon is typically a picture indicating the function of the 
underlying application. 

The definitions necessary to use icons are found in the file 
<suntool/icon. h>, which is included by default when you include the file 
<suntool/sunview. h>. 

To give you a feeling for what you can do with icons, the following page lists the 
available icon attributes, functions and macros. Many of these are discussed in 
the rest of this chapter and elsewhere (use the Index to check). All are briefly 
described with their arguments in the menu summary tables in Chapter 19, Sun- 
View Interface Summary: 

□ the Icon Attributes table begins on page 328; 

□ the Icon Functions and Macros table begins on page 329. 
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Icon Attributes 

ICON_FONT 

ICON_IMAGE_RECT 

ICON_WIDTH 

ICON_HEIGHT 

ICON_LABEL 


ICON_IMAGE 

ICON_LABEL_RECT 



Icon Functions and Attributes 

icon_create(attributes) 

icon set(icon, attributes) 

icon_destroy(icon) 

DEFINE_ICON_FROM_IMAGE(name, image) 

icon_get(icon f attribute) 



14.1. Using Images 
Generated With 

iconedit 


You can create and edit images easily using the program iconedit(l). The 
output of iconedit is a file containing an array of shorts representing the 
image. In order to use the image in a program, you must first define a static 
memory pixrect containing this data. Thempr_static () macro is provided 
for this purpose. 

The first argument to mpr_static () is the name of the pixrect to be defined. 
Next come the width, height and depth of the image, typically 64, 64 and 1. The 
last argument is the array of shorts containing the bit pattern of the icon image. 
For example: 

-—- 1 

static short icon_image[] = { 

♦include ,, file_generated_by_iconedit" 

}; 

mpr_static (icon__pixrect, 64, 64, 1, icon_image); 

< ____J 

The statically defined image is passed in to icon_create () at run time: 

-—-> 

my_icon = icon_create (ICON_IMAGE, &icon__pixrect, 0) ; 
s___ ' 

Once you have created an icon, you can retrieve and modify its attributes with 
icon_get () and icon_set (), and destroy it with icon_destroy (). 

Instead of creating the icon dynamically with icon_create (), you can use 
the DEFINE_IC0N_FR0M_IMAGE () macro to generate a static icon. 88 
---■> 

static short icon_image[] = { 

♦include "file_generated_by_iconedit" 

}; 

DEFINE_ICON_FROM_IMAGE (icon, icon_image) ; 

< __—- ' 

This macro statically allocates a structure representing an icon. Note that you 

88 The structure generated is actually an extern. 
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WARNING 


14.2. Modifying the Icon’s 
Image 


14.3. Loading Icon Images 
At Run Time 


must pass the address of this structure — & icon in the example above — into 
icon_get (), icon_set (), and icon_destroy (). 

The DEFINE_IC0N_FR0M_IMAGE () macro may not be supported in future 
releases. We reccommend that you use icon_create () instead. 


It is often useful to change the icon’s image dynamically, rather than simply 
using the icon as a static placeholder. When mailtool receives new mail, for 
example, it lets the user know by modifying its icon to show a letter arrived in 
the mailbox, clocktool uses its icon to represent a moving clock face. 

The steps to follow in modifying an icon’s image are: 

□ get the frame’s icon (attribute FRAME_iCON); 

□ get the icon’s pixrect (attribute I C0N_IMAGE); 

□ modify the pixrect as desired, or substitute a new pixrect; 

□ give the pixrect with the new image back to the icon; 
o give the new icon back to the frame. 

For example: 

- --> 

modify_icon(frame); 


Frame frame; 

Icon icon; 

Pixrect *pr; 

icon = (Icon) window__get (frame, FRAME_ICON) ; 
pr = (Pixrect *) icon_get(icon, ICON_IMAGE); 

(modify pr) 

icon_set(icon, ICON_IMAGE, pr, 0); 
window_set(frame, FRAME_ICON, icon, 0); 


Often it is sufficient to define the image for a program’s icon at compile time, 
with mpr_stat ic (). However, you may want to allow the user to create his 
own icon images, and give the names of the files containing the images to your 
program as command-line arguments. Then you can load the images from the 
files the user has specified. Routines to load icon images from files at run time 
are described in Chapter 11 of the SunView 1 System Programmer’s Guide. 


WARNING 


14.2. Modifying the Icon’s 
Image 


14.3. Loading Icon Images 
At Run Time 
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Scrollbars 


The canvas, text and panel subwindows have been designed to work with 
scrollbars. The text subwindow automatically creates its own vertical scrollbar. 
For canvases and panels, it is your responsibility to create the scrollbar and pass 
it in with the attributes WIN_VERT ICAL_S CROLLBAR or 
WIN_HORIZONTAL_SCROLLBAR. 

Section 15.2, Scrollbar User Interface, describes how the user interacts with 
scrollbars. Basic scrollbar usage is covered in Section 15.3, Creating, Destroy¬ 
ing and Modifying Scrollbars, and programmatic scrolling is covered in Section 
15.4, Programmatic Scrolling. 

You may want to use scrollbars in an application not based on canvases, text 
subwindows or panels, in which case you must manage the interaction with the 
scrollbar directly. For an explanation of how to do this, see the Scrollbars 
chapter in the SunView 1 System Programmer’s Guide. 

Header Files The definitions necessary to use scrollbars are found in the header file 

<suntool/scrollbar.h> 

Summary Listing and Tables To give you a feeling for what you can do with scrollbars, the following page 

contains a list of the available scrollbar attributes, functions and macros. Many 
of these are discussed in the rest of this chapter and elsewhere (use the Index to 
check). All are briefly described with their arguments in the scrollbar summary 
tables in Chapter 19, SunView Interface Summary: 

□ the Scrollbar Attributes table begins on page 362; 

□ the Scrollbar Functions table begins on page 365. 
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Scrollbar Attributes 

SCROLL_ABSOLUTE_CURSOR 


SCROLL_NOT I FY_CL I ENT 

SCROLL_ACTIVE_CURSOR 


SCROLL_NORMALIZE 

SCROLL_ADVANCED_MODE 


SCROLL_OBJECT 

SCROLL_BACKWARD_CURS OR 


SCROLL__OBJECT_LENGTH 

SCROLL_BAR_COLOR 


SCROLL_P AGE_BUTT ON S 

SCROLL_BAR_DISP LAY_LEVEL 


SCROLL_PAGE_BUTTON_LENGTH 

SCROLL_BORDER 


SCROLL_PAINT_BUTTONS_PROC 

SCROLL_BUBBLE_COLOR 


SCROLL_PIXWIN 

SCROLL_BUBBLE_DISP LAY_LEVEL 


SCROLL_P LACEMENT 

SCROLL_BUBBLE_MARGIN 


SCROLL_RECT 

SCROLL_DIRECTION 


SCROLL_REPEAT_TIME 

SCROLL__END_P 0 INT_ARE A 


SCROLL_REQUEST__MOT I ON 

SCROLL_FORWARD_CURSOR 


SCROLL_REQUEST_OFFSET 

SCROLL_GAP 


SCROLL_THICKNESS 

SCROLL_HEIGHT 


SCROLL_T 0_GRID 

SCROLL_JL AS T_V IE W_S TART 


SCROLL_TOP 

SCROLL_LEFT 


SCROLL_VIEW_LENGTH 

SCROLL_LINE_HEIGHT 


SCROLL_VIEW_START 

SCROLL_MARGIN 


SCROLL__WIDTH 

SCROLL_MARK 




_ Scrollbar Functions and Macros _ 

scrollbar_create(attributes) scrollbar_paint(scrollbar) 

scrollbar_destroy(scrollbar) scrollbarjpaint_clear(scrollbar) 

scrollbar_get(scrollbar, attribute) scrollbar_clear_bubble(scrollbar) 

scrollbar_set(scrollbar, attributes) scrollbar_paint_bubble(scrollbar) 

scrollbar scroll to(scrollbar, new_view_start) _ 


Asun 
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15.1. Scrolling Model 

Scrollbars allow the user to control which portion of an object is visible when the 
object is larger than the window it is displayed in. Within the scrollbar is a 
darker area called the bubble. The size and position of the bubble within the bar 
tell the user where he is in the object and how much of the object is visible. By 
moving the bubble within the bar, the user brings different portions of the object 
into view. 

The length of the object, the length of the visible portion of the object, and the 
offset of the visible portion within the object are given by the attributes 
SCROLL_OBJECT_LENGTH, SCROLL_VIEW_LENGTH, and 
SCROLL_VlEW_START. The relationship between these three view-space 
metrics is shown in the figure on the next page. 
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Figure 15-1 Scrolling Model 



Figure 15-1 shows a two-page document being viewed within a window roughly 
half the size of the document. The three view-space attributes 

SCROLL_OBJECT_LENGTH, SCROLL_VIEW_LENGTH, and 

SCROLL - VIEW START are shown superimposed on the document. Note the 
relative size and position of the bubble within the scrollbar — it is roughly half 
the size of the window and positioned near the bottom. 
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15.2. Scrollbar User 
Interface 

Types of Scrolling Motion The default scrollbar is vertical, with page buttons at the top and bottom. To 

scroll, the user moves the cursor into the scrollbar (either the bar itself or one of 
the page buttons) and clicks one of the mouse buttons. The following table 
describes the available scrolling actions and how they are generated: 

Table 15-1 Scrolling Motions 


Mouse Button 

Cursor Location 

Scrolling Action 

LEFT 

page button 

Line forward 

RIGHT 

page button 

Line backward 

MIDDLE 

page button 

Page forward 

MIDDLE (shifted) 

page button 

Page backward 

LEFT 

bar 

Line opposite cursor goes to top 

RIGHT 

bar 

Top line comes to cursor 

LEFT (shifted) 

bar 

Bottom line comes to cursor 

RIGHT (shifted) 

bar 

Line opposite cursor goes to bottom 

MIDDLE 

bar 

The line whose offset into the 
scrolling object approximates that 
of the cursor into the scrollbar is 
positioned at top (“thumbing”). 


Undoing a Scroll 


Holding the button down within the scrollbar causes the cursor to change, pre¬ 
viewing the scrolling action for that button. Releasing the button causes the 
scrolling action to be performed, or, if the user holds down the mouse button, the 
scrolling motion will start in repeating mode. 


(Shift l -MIDDLE mouse button positions the viewing window to the most recent 
position which was left by an absolute motion (thumbing or undoing). The undo¬ 
ing position is initialized to the beginning of the scrollable object. 
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15.3. Creating, Destroying Scrollbars are created and destroyed with scrollbar_create () and 

and Modifying scrollbar_destroy (). To take the simplest possible example, you get a 

Scrollbars default scrollbar (vertical, on the left edge of the subwindow, etc.) by calling: 


r - 

\ 

Scrollbar bar; 


bar = scrollbar_create(0); 

_ > 

You would destroy the scrollbar with the call: 

f -- 

scrollbar_destroy(bar); 

__ 



The appearance and behavior of a given scrollbar is determined by the values of 
its attributes. Here’s an example of a non-default scrollbar: 


/— 

bar_l = scrollbar_create( 




SCROLL_P LACEMENT, 

SCROLL__EAST, 



SCROLL_BUBBLE_COLOR, 

SCROLL_BLACK, 



SCROLL_BAR_DISPLAY_LEVEL, 

SCROLL__ACTI VE, 



SCROLL_BUBBLE_DISP LAY_LEVEL, 

SCROLL__ACTIVE, 



SCROLL_DIRECTION, 

SCROLLJVERTICAL, 



SCROLLJTHICKNESS, 

20, 



SCROLL_BUBBLE_MARGIN, 

4, 



0), 



s. 





In the above call, setting SCROLL_PLACEMENT to SCROLL_EAST will cause 
the scrollbar to appear on the right edge of the subwindow. The scrollbar will be 
20 pixels wide with a black bubble 4 pixels from each edge of the bar. The bar 
and bubble will be shown only when the cursor is in the scrollbar. 

You can modify and retrieve the attributes of a scrollbar with the two routines: 

scrollbar_set(scrollbar, attributes) 

Scrollbar scrollbar; 

<attribute-list> attributes; 

caddr_t 

scrollbar_get(scrollbar, attribute) 

Scrollbar scrollbar; 

Scrollbar_attribute attributes; 

If the scrollbar parameter is NULL, scrollbar_get () returns 0. 

SCROLL_RECT, SCROLLJTHICKNESS, SCROLL_HEIGHT and 
SCROLL_WIDTH do not have valid values until the scrollbar is passed into the 
subwindow. As a work-around for this problem, the special symbol 
SCROLLBAR has been provided. You can determine the default thickness of a 
scrollbar before it has been attached to a subwindow with the call: 


#sun 
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f 


thickness = (int) scrollbar_get(SCROLLBAR, SCROLL_THICKNESS) ; 


J 


This convention is currentiy only implemented for SCROLL_THlCKNESS. 

If you set the SCROLL_THiCKNESS attribute then you must also set the 
SCROLL_DIRECTlON of the scrollbar, since the dimension of the scrollbar that 
is altered by SCROLL_THICKNESS depends on the orientation of the scrollbar. 

The figures on the next page show some of the attributes controlling the visual 
appearance of a scrollbar. 89 Figure 15-2 illustrates the attributes that control the 
scrollbar appearance. Figure 15-3 illustrates the attributes that control the 
scrollbar placement. 


89 For a complete list of the scrollbar attributes see the Scrollbar Attributes table in Chapter 19, SunView 
Interface Summary. 
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Figure 15-2 Attributes Controlling Scrollbar Appearance 


Scrollbar Attributes 


SCROLL_RIGHT 


SCROLL.THICKNESS 
SCROLL_BAR_C0L0R 



SCROLL.BLACK 

SCROLL_VHITE 



Page Button Attributes 


SCROLL_PAGE_BUTTONS: TRUE or FALSE 
SCROLL_PAGE_BUTTON_LENGTH 


Bubble Attributes: 
SCROLL_BUBBLE_HARGIN 
SCR0LL_BUBBLE_C0L0R 

■ SCROLL.BLACK 
n SCROLI_GREY 


Figure 15-3 Scrollbar Placement Attributes 


SCROLL_DIRECTION: 

SCROLL VERTICAL SCROLL HORIZONTAL 


I 
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15.4. Programmatic 
Scrolling 


To scroll to a given location from your program, call: 

scrollbar_scroll_to(scrollbar, new_view_start) 

Scrollbar scrollbar; 
long new_view_start; 

This routine saves the current value of SCROLL_viEW_START as 
SCROLL_LAST_VIEW_START, sets SCROLL_VIEW_START to the value 
passed in as new_view_start, and posts a scroll event to the scrollbar’s 
client (i.e. the canvas, panel or text subwindow) using the Notifier. This has the 
same effect as if the user had requested a scroll to new_view_start. 
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16.1. Getting the Primary Selection 

16.2. Setting the Primary Selection 
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The Selection Service 


The Selection Service provides for flexible communication among window appli¬ 
cations. You can use the Selection Service to query and manipulate the selec¬ 
tions the user has made. 

This chapter gives only the simplest example of using the Selection Service. To 
find out more about the Selection Service and the other functionality it provides, 
refer to Chapter 9 of the SunView 1 System Programmer’s Guide. 

The definitions necessary to use the Selection Service are found in the include 
file <suntool/seln .h>. 
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16.1. Getting the Primary The primary selection is the selection made by the user without holding down 

Selection any of the function keys, and is indicated with reverse-video highlighting on the 

screen. 

The routine below is taken from the program filer, listed in Appendix A. It 
retrieves the primary selection by first asking the Selection Service which win¬ 
dow has the primary selection, then asking that window for the characters that 
are in the selection, saving them in a static buffer, and returning a pointer to that 
buffer: 

#define <suntool/seln.h> 

#define MAX_FILENAME_LEN 256 
char * 

get_selection () 

{ 

static char filename[MAX_FILENAME_LEN]; 

Seln_holder holder; 

Seln_request ^buffer; 

holder * seln_inquire(SELNJPRIMARY); 

buffer = seln_ask(&holder, SELN_REQ_CONTENTS_ASCII, 0, 0); 
strncpy(filename, 

buffer->data + sizeof(Seln_attribute), 

MAX_FILENAME_LEN); 

return (filename); 

} 

_ ) 


This example has been kept simple by removing error checking. The code relies 
on the fact that if there is no primary selection, or the Selection Service process is 
not running, or the holder of the primary selection failed to returned the selection 
string, then the buffer returned by seln_ask () will have an empty string for 
the selection characters. 

The routine also assumes that the selection will be no more than 256 characters 
long. seln_ask () will handle selections of up to about 2000 characters. To 
find out how to handle arbitrarily large selections, or selections other than the pri¬ 
mary selection, refer to the SunView 1 System Programmer’s Guide. 


16.2. Setting the Primary 
Selection 


For an example of a program which sets, and responds to queries about, the 
selection, see selndemo, in Chapter 9 of the SunView 1 System Programmer’s 
Guide. 
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The Notifier 


The Notifier is a general-puipose mechanism for distributing events to a collec¬ 
tion of clients within a process. It detects events in which its clients have 
expressed an interest, and dispatches these events to the proper clients, queuing 
client processing so that clients respond to events in a predictable order. 

An overview of the notification-based model is given in Chapter 2, The SunView 
Model. 

To encourage the porting of existing applications, the Notifier has provisions to 
allow programs to run in the Notifier environment without inverting their control 
structure. See Section 17.6, Porting Programs to SunView. 

Header Files The definitions for the Notifier are contained in the file 

<sunwindow/notif y. h>, which will be included indirectly when you 
include <suntool/sunview .h>.^° 

Related Documentation This chapter will suffice for the majority of SunView applications. See the 

chapters titled Advanced Notifier Usage and The Agent and Tiles in the Sun¬ 
View 1 System Programmer’s Guide for more information on the Notifier and 
SunView’s usage of it. When looking up Notifier-related information, look first 
in the index to this book, then in the index to the SunView 1 System 
Programmer’s Guide. 

Summary Listing and Table To give you a feeling for what you can do with the Notifier, the following page 

contains a list of the available Notifier functions. Many of these are discussed in 
the rest of this chapter and elsewhere (use the Index to check). All are briefly 
described with their arguments in the Notifier Functions table beginning on page 
343 in Chapter 19, SunView Interface Summary. 


90 For those programmers utilizing the Notifier outside of SunView (a perfectly reasonable thing to do), the 
code that implements the Notifier is found in /usr/lib/libsunwindow. a. 
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Notifier Functions 

notify_default_wait3(client, pid, status*, rusage) 
notify_dispatch() 
notify_do_dispatch() 

notify_interpose_destroy_func(client, destroy_func) 
not if y__interpose_event__f unc (client, event_func, type) 
notify_itimer_value(client, which, value) 
notify_next_destroy_func(client, status) 
notify_no_dispatch() 
notify_j?error (s) 

notify_set_destroy_func(client, destroy_func) 
notify_set_exception_func(client, exception__func, fd) 
notify_set_input__func (client, input__func, fd) 

notify_set_itimer_func(client, itimer_func, which, value, ovalue) 
notify_set_signal_func (client, signal__func, signal, when) 
notify_start() 
notify_stop() 

notify_set_output_func(client, output_func, fd) 
notify_set_wait3__func (client, wait3_func, pid) 
notify_veto_destroy(client) 
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17.1. When to Use the 
Notifier 


17.2. Restrictions 


Don’t Call... 

signal(3) 

sigvec(2) 

setitimer(2) 

alarm(3) 

getitimer(2) 

wait 3(2) 


Since the Notifier is used by the SunView libraries, any program that uses Sun- 
View implicitly uses the Notifier. You will have to use the Notifier explicitly if 
you want to do any of the following: 

a Catch signals, e.g., SIGCONT. 

□ Notice state changes in processes that your process has spawned, e.g., a child 
process has died. 

□ Read and write through file descriptors, e.g., using pipes. 

□ Receive notification of the expiration of an interval timer, e.g., so that you 
can provide some blinking user feedback. 

□ Extend, modify or monitor SunView Notifier clients, e.g., noticing when a 
frame is opened, closed or about to be destroyed. 

□ Use a non-notification-based control structure while running under Sun¬ 
View, e.g., porting programs to SunView. 

The Notifier imposes some restrictions on its clients which designers should be 
aware of when developing software to work in the Notifier environment. These 
restrictions exist so that the application and the Notifier don’t interfere with each 
other. More precisely, since the Notifier is multiplexing access to user process 
resources, the application needs to respect this effort so as not to violate the shar¬ 
ing mechanism. 

Assuming an environment with multiple clients with an unknown notifier usage 
pattern, you should not use any of the following system calls or C library rou¬ 
tines: 91 

The Notifier is catching signals on the behalf of its clients. If you set up your 
own signal handler over the one that the Notifier has set up then the Notifier will 
never notice the signal. 

The same applies for sigvec(2) as does for signal(3), above. 

The Notifier is managing two of the process’s interval timers on the behalf of its 
many clients. If you access an interval timer directly, the Notifier could miss a 
timeout. Use notif y_set_itimer_func () instead of setitimer(2). 

Because alarm(3) sets the process’s interval timer directly, the same applies for 
alarm(3) as does for setitimer(2), above. 

When using a notifier-managed interval timer, you should call 
notify_itimer_value () to get its current status. Otherwise, you can get 
inaccurate results. 

The Notifier notices child process state changes on behalf of its clients. If you do 
your own wait 3(2), then the notifier may never notice the change in a child 

91 A future release may provide modified versions of some of these forbidden routines that will allow their 
use without restriction. However, the restrictions described in Don't Catch. .below, will continue to be 
germane. A signal () Replacement for Notifier Compatibility , in Section 17.4, provides a code patch for 
programs that catch signals. 


17.1. When to Use the 
Notifier 


17.2. Restrictions 


Don’t Call... 

signal(3) 

sigvec(2) 

setitimer(2) 

alarm(3) 
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wait 3(2) 
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wait(2) 

ioctl(2) (..., FIONBIO,...) 

ioctl(2) (..., FIOASYNC,...) 

system(3) 


Don’t Catch... 

SIGALRM 

SIGVTALRM 

SIGTERM 

SIGCHLD 

SIGIO 

SIGURG 


process or you may get a change of state for a child process in which you have no 
interest. Use notify_set_wait3_func () instead of wait3(2). 

The same applies for wait(2) as does for wait3(2), above. 

This call sets the blocking status of a file descriptor. The Notifier needs to know 
the blocking status of a file descriptor in order to determine if there is activity on 
it f cntl(2) has an analogous request that should be used instead of ioctl(2). 

This call controls a file descriptor’s asynchronous io mode setting. The Notifier 
needs to know this mode in order to determine if there is activity on it 
f cnt 1(2) has an analogous request that should be used instead of ioct 1(2). 

In the SunOS, this function calls signal(3) and wait(2). Hence you should 
avoid using this for the reasons mentioned above. Calls to system(3) should be 
replaced with something like the following. 

/-——-\ 

if((pid = vfork()) == 0) { 

(void) execl(”/bin/sh", "sh" f "-c", str f (char *)0); 
_exit(127); 

} 

notify__set_wait3_func (me, my_handler, pid); 


Clients should not have to catch any of the following signals. If you are, then 
you are probably also making one of the forbidden calls described above. You 
might also be utilizing the Notifier inappropriately if you think that you have to 
catch any of these signals. The Notifier catches these signals itself under a 
variety of circumstances: 

Caught by the Notifier’s interval timer manager. Use 
notif y_set_itimer_func () instead. 

The same applies for SIGVTALRM as does for SIGALRM above. 

Caught by the Notifier so that it can tell its clients that the process is going away. 
Use not if y_set_destroy_f unc () if that is why you are catching 
SIGTERM. 

Caught by the Notifier so that it can do child process management Use 
notify_set_wait3_func () instead. 

Caught by the Notifier so that it can manage its file descriptors that are running in 
asynchronous io mode. Use notify_set_input_f unc () 92 or 
notif y_set_output_func () if you want to know when there is activity 
on your file descriptor. 

Caught by the Notifier so that it can dispatch exception activity on a file descrip¬ 
tor to its clients. Use notif y_set_exception_func () if you are looking 
for out-of-band communications when using a socket. 


92 Do not use a NULL client handle when you use not i f y_set_input_f unc () or the Notifier will go 
into an infinite loop. 
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If you think you have to catch one of these signals, then be sure to use 
notify_set_signal_func(). 


17.3. Overview 

How the Notifier Works Before it can receive events, a client must advise the Notifier of the types of 

events in which it is interested. It does this by registering an event handler func¬ 
tion (which it must supply) for each type of event in which it is interested. When 
an event occurs, the Notifier calls the event handler appropriate to the type of 
event. 

Figure 17-1 shows an overview of how the notification mechanism works. 


Figure 17-1 Overview of Notification 



— -> Client registers event proc at initialization time 
-=► Notifier calls back to client when event received 

Client Handles The Notifier uses a client handle as the unique identifier for a given client. The 

Notifier, without interpreting the client handle in any way, uses it to associate 
each event with the event handler for a given client. 

The only requirement for a client handle is that it must be unique (within a pro¬ 
cess). Since a program text address or the address of an allocated data block are 
guaranteed to be unique, they can be used. Since stack addresses are not in gen¬ 
eral guaranteed to be unique they should not be used. Internally, SunView uses 
the object handles returned from window_create () as notifier client handles. 

Types of Interaction Client interaction with the Notifier falls into the following functional areas: 

□ Event handling — A client may receive events and respond to them via 
event handlers. Event handlers do the bulk of the work in the Notifier 
environment. The various types of events are in Section 17.4, Event Han¬ 
dling. 

□ Interposition — A client may request that the Notifier install a special type 
of event handler (supplied by the client) to be inserted (or interposed) ahead 
of the current event handler for a given type of event and client. This allows 
clients to screen incoming events and redirect them, and to monitor and 
change the status of other clients. Examples of interposition may be found 
below under Monitoring a Frame’s State. 
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□ Notifier control — A client may exercise control over when dispatching of 
events occurs. See Section 17.6, Porting Programs to SunView. 

17.4. Event Handling This section describes how to be notified of UNIX-related events and notifier sup¬ 

ported destroy events (see Chapter 6, Handling Input, for a description of 
SunView-defined events). UNIX events are low-level occurrences that are mean¬ 
ingful at the level of the operating system. These include signals (software inter¬ 
rupts), input pending on a file descriptor, output completed on a file descriptor, 
tasks associated with managing child processes, and tasks associated with 
managing interval timers. 

A client establishes an interest in a certain type of event by registering an event 
handler procedure to respond to it. The event handler for a given type of event 
has a mandatory calling sequence, as described below. All event handlers return 
a value of either notify_done or notify_ignored depending on whether 
the event was acted on in some way or failed to provoke any action, respectively. 

When registering an event handler, the registration procedure returns a pointer to 
the function that was in place previous to the current call. On initialization, the 
Notifier sets up its internal tables by registering “dummy” functions as place¬ 
holders. These dummy functions are no-op functions with no harmful side- 
effects. The first time a client registers a given type of event handler, it will 
receive a pointer to a “dummy” function. 

The following sections describe common usages of various types of events. 

Child Process Control Events Let’s say that you want to fork a process to perform some processing on your 

behalf. UNIX requires that you perform some housekeeping of that process. The 
minimum housekeeping required is to notice when that process dies and “reap” 
it. You can register a wait3 event handler, 93 which the Notifier will call when¬ 
ever a child process changes state (e.g. dies), by calling: 

Notify_func 

notify_set__wait3_func (client, wait3_func, pid) 
static Notify_client client; 

Notify_f unc wait3_func; 

int pid; 


“Reaping” Dead Processes Clients using child process control which simply need to perform the required 

reaping after a child process dies can use the predefined 

notif y_def ault_wait3 () as their wait3 event handler. For example: 


93 The name wait3 event originates from the wait 3(2) system call. 
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* 


Results from a Process 



-s 

♦include <sunwindow/notify.h> 

static int my__client__object; 

static Notify_client *me = &my_client__object; 

int pid; 

if ((pid = my_fork())) 

(void) notify__set_wait3_func (me, notify__default_wait3, 

pid) ; 

/* Start dispatching events */ 

(void) notify_start(); 

v_/ 


This is sufficient to have your child process reaped on its death. The Notifier 
automatically removes a dead process’s wait3 event handler from its internal data 
structures. 

NOTE The use of me as a client handle is arbitrary, but illustrates one method of gen¬ 
erating a unique client handle. 

A more interesting application might actually receive some results from the pro¬ 
cess it forked. In this case, the application would supply its own wait3 event 
handler 94 . For example: 

— 

♦include <sunwindow/notify.h> 

♦include <sys/wait.h> 

♦include <sys/time.h> 

♦include <sys/resource.h> 

static Notify_value my_wait3_handler(); 

/* Register a wait3 event handler */ 

(void) notify_set_wait3__func (me, my__wait3_handler, pid) ; 

/* Start dispatching events */ 

(void) notify_start(); 

static Notify_value 

my_wait3_handler(me, pid, status, rusage) 

Notify__client me; 
int pid; 

union wait *status; 
struct rusage *rusage; 

if (WIFEXITED(^status)) { 

/* Child process exited with return code */ 
my_return_code_handler (me, statu s->w__ret code) ; 

/* Tell the notifier that you handled this event */ 
return (NOTIFY__DONE) ; 

} 

/* Tell the notifier that you ignored this event */ 
return (NOTIFY_IGNORED); 

V_ ) 


94 See the wait (2) manual page for details of union wait and struct rusage. 



microsystems 


Revision A, of May 9, 1988 







290 SunView 1 Programmer’s Guide 


Input-Pending Events (pipes) A program may need to know when there is input pending on a file descriptor— 

for instance, on one end of a pipe. Let’s extend our previous example a bit to 
include reading data from a pipe connected to a process that we have forked. 

You can register an input-pending event handler which the Notifier will call 
whenever whenever there is input pending on a file descriptor 95 by calling: 

Notify_func 

notify_set_input_func(client, input_func, fd) 

Notify_client client; 

Notify_func input_func; 

int fd; 

The calling sequence for the input_f unc () you supply is as follows: 

Not if y__value 
input__func (client, fd) 

Not if y__client client ; 
int fd; 


Example: Reading a Pipe 


--— \ 

♦include <sunwindow/notify.h> 

static Notify_value my_pipe_reader(); 

int fildes[2]; 

/* Create a pipe */ 
if (pipe(fildes) == -1) { 

perror("pipe"); 
exit (1); 

} 

/* Register an input-pending event handler */ 

(void) notify_set_input_func(me, my__pipe_reader, fildes[0]); 
... do fork and dispatching from wait 3 event example ... 

... do fork and dispatching from wait 3 event example ... 

static Notify_value 
my_pipe_reader(me, fd) 

Notify_client me; 
int fd; 

/* Read the pipe (fd) */ 

/* Tell the notifier that the input event is handled */ 
return (NOTIFY_DONE); 

' 

In the above example, the application uses the Notifier to read from the pipe 
because it doesn’t want to block on input pending on the pipe. In the case of a 
SunView program, the program wants to return back to the Notifier’s central 
dispatching loop so that the user can interact with the window while waiting for 
input to become available on the pipe. 


95 The file descriptor can be in blocking or non-blocking mode, or in asynchronous mode; the Notifier 
handles both as long as you have used f cnt 1(2) to set the modes. 
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When you close any file descriptor that has been registered with the Notifier you 
should unregister it. To do this, call notif y_set_input_func () with a 
notify_func of NOTIFY_FUNC_NULL. 96 ~ 

Signals are UNIX software interrupts. The Notifier multiplexes access to the 
UNIX signal mechanism. A client may ask to be notified that a UNIX signal 
occurred either when it is received (asynchronously) and/or later during normal 
processing (synchronously). 

Clients may define and register a signal event handler to respond to any UNIX 
signal desired. However, many of the signals that you might catch in a tradi¬ 
tional UNIX program may be being caught for you by the Notifier (see Don’t 
catch above). 

CAUTION Clients of the Notifier must not directly catch any UNIX signals using sig¬ 
nal (3) or sigvec(2). Regardless of whether clients choose synchronous or 
asynchronous signal notification, they must use the signal event mechanism 
described in this section. See Section 17.2, Restrictions. 

You can register a signal event handler which the Notifier will call whenever a 
signal has been caught by calling: 

Notify_func 

not if y_set_signal__func (client, signal_func, signal, when) 
Notif y__client client ; 

Notify_func signal_func; 

int signal; 

Notify_signal_mode when; 

when can be either NOTIFY_SYNC or NOTIFY_ASYNC. NOTIFY_SYNC 
causes notification during normal processing, that is, the delivering of the signal 
is delayed, so that your program doesn’t receive it at an arbitrary time. 
N0TIFY_ASYNC causes notification immediately as the signal is received, — 
this mode mimics the UNIX signal(3) semantics. 

You should rewrite applications to use notif y_set_signal_func (). 
However, the Notifier routine notif y_set_signal_f unc () does not fully 
emulate the signal(3) function. It does not handle errors the same way sig- 
nal(3) does. Errors from signal(3) are indicated by a -1 return value, and 
the value of errno is set to EINVAL. 

The errors for notif y_set_signal_f unc () are not communicated back to 
the caller, but error messages are printed. For example, if the signal number is 
not valid, the Notifier prints 


but its return value indicates success; the signal(3) system call does not print a 
message, but returns -1 and sets errno to EINVAL. As another example, if 

96 This method of passing in a NOTIFY_FUNC_NULL to unregister an event handler from the Notifier 
works for any type of event 


/ - — . . 

Bad signal number 

v '• • - v - •• • 


A signal () Replacement for 
Notifier Compatibility 


Closing the Pipe 


Signal Events 
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SIGKILL or SIGSTOP are ignored or a handler supplied, the Notifier prints 
-. 

Notifer assertion botched: Unexpected error: sigvec 

v . ’ • ■ •- - '• • ■■■■■■ _:_ : " _ 

but its return value indicates success, while sign a 1(3) does not print a message, 
returns value of -1, and sets errno to EINVAL. 

The work-around is to use the following replacement function for the C library 
version of signal(3). This code converts signal () calls into 
notify_set_signal_func () calls. Explicitly loading this code will over¬ 
ride the loading of the C library’s version of signal (). This approach works 
only if all the signal handlers registered by signal () only look at the first 
argument passed to them when a signal is received. Also, no Notifier client han¬ 
dle may be a small integer. 

< ' 
♦include <sunwindow/notify.h> 

♦include <errno.h> 

int (* 

signal (sig, func)) () 
int sig,(*func)(); 

if ( (sig <1 || sig > NSIG) || 

(sig — SIGKILL || sig — SIGSTOP) ) { 

errno - EINVAL; 
return(BADSIG); 

} 

if (sig == SIGCONT && func == SIG_IGN) { 
errno = EINVAL; 
return(BADSIG); 

} 

return ( (int (*) ())notify_set_signal_func(sig, func, 

sig, NOTIFY_ASYNC)); 

s_ ) 


Example: Writing to a Pipe Let’s extend our on-going example by writing on the pipe. Writing to a pipe that 

has no process at the other end to receive the message causes a SIGPIPE to be 
generated by UNIX. By default, an uncaught SIGPIPE causes a premature pro¬ 
cess termination. So, we are going to catch SIGPIPE so that our process 
doesn’t get killed if we start a process that dies . 97 


97 We are glossing over the part about actually writing to the pipe. If we wanted to write something to the 
pipe and then get some notification about when the write had actually completed (i.e., the other process had read 
it) we would use the not if y_set_output_f unc () call. The calling sequences for this routine and its 
event handler are exactly the same as those for not i f y_set_input_f unc () (previously described). 
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f — 

♦include <sunwindow/notify.h> 

♦include <signal.h> 

\ 

static Notify_value my_sigpipe_handler(); 


... do pipe from input-pending example ... 

... do notify set_input_func from input-pending example ... 

... do fork from wait 3 event example ... 

/* Register a signal event handler */ 

(void) notify set signal__func (me, my_sigpipe__handler, 

SIGPIPE, NOTIFY_ASYNC) ; 

/* Write a message on the pipe */ 


/* Start dispatching events */ 

(void) notify_start(); 


static Notify__value 

my sigpipe_handler(me, signal, when) 
Notify_client me; 

int signal; 

Notify_signal__mode when; 


/* 

* This is a no-op function meant only 

* being killed because we didn't have 
*/ 

return (NOTIFY_I GNORED); 

-—— 

to prevent us from 
a SIGPIPE handler. 

_> 


This example wouldn’t actually show my_sigpipe_handler () being called 
unless you set up the child process to die right away. 


An asynchronous signal notification can come at any time (unless blocked using 
sigblock(2)). This means that the client can be executing code at any arbi¬ 
trary place. Great care must be exercised during asynchronous processing. 

It is rarely safe to do much of anything in response to an asynchronous signal. 
Unless your program has taken steps to protect its data from asynchronous 
access, the only safe thing to do is to set a flag indicating that the signal has been 
received. 

When in an asynchronous signal event handler, the signal context and signal code 
is available from the follow routines: 

int 

notify_get_signal_code() 

struct sigcontext * 
notify_get_signal_context () 

The return values of these routines are undefined if called from a synchronous 
signal event handler. 
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Timeout Events 


Example: Periodic Feedback 


A client may require notification of an expired timer based on real time (approxi¬ 
mate elapsed wall clock time; IT IMER_REAL) or on process virtual time (CPU 
time used by this process; ITIMER__VIRTUAL). To receive this type of 
notification, the client must define and register a timeout event handler. 


Notify_func 

notify_set_itimer_func(client, itimer_func, which, value, 

ovalue) 

Notify_client client; 

Notify_func itimer_func; 

int which; 

struct itimerval *value, *ovalue; 


The semantics of which, value and ovalue parallel the arguments to seti- 
timer(2) (see the getitimer(2) manual page), which is either 
ITIMER_REAL or ITIMER_VIRTUAL. 

As an example, we want to provide some form of blinking feedback. We do this 
by setting up an interval timer when we want to blink. We turn the internal timer 
off when we no longer need the blinking. 98 


98 This code segment should be wrapped in, say, a panel notify procedure, in order to be actually run. 
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-— > 

#include <sunwindow/notify.h> 

♦include <sys/time.h> 

static int blinking__required; /* blinking desired */ 
static int blinking; /* blinking enabled */ 

♦define ITIMER_NULL ((struct itimerval *)0) 
static Notify__value my_blinker () ; 

if (blinking_required && !blinking) { 

struct itimerval blink_timer; 

/* Set up interval with which to RELOAD the timer */ 
blink_timer.it_interval.tv_usec = 0; 
blink_timer.it_interval.tv_sec = 1; 

/* Set up INITIAL value with which to SET the timer */ 
blink_timer. it__value. tv_usec = 0; 
blink_timer. it_value .tv__sec = 1; 

/* Turn on interval timer for client */ 

(void) notify_set__itimer_func (me, my__blinker, 

ITIMER_REAL, &blink_timer, ITIMER_NULL); 
blinking = 1; 

} else if (!blinking_required && blinking) { 

/* Turn off interval timer for client */ 

(void) notify_set_itimer__func (me, my_blinker, 

ITIMER_REAL, ITIMER_NULL f ITIMER_NULL); 
blinking = 0; 

} 

static Notify_value 
my_blinker(me, which) 

Notify__client me; 
int which; 

/* Do the blink */ 

return (N0TIFY_D0NE); 

V_ ) 


Polling Interval timers can be used to set up a polling situation. There is a special 

value argument to notif y_set_it imer_func () that tells the Notifier to 
call you as often and as quickly as possible. This value is the address of the 
following constant: 

Struct itimerval NOTIFY_POLLING_ITIMER; /*{{0,1}, {0,1} }*/ 

This high speed polling can consume all of your machine’s available CPU time, 
but may be appropriate for high speed animation. It is used in the program 
spheres, which shows one way to convert and old SunWindows gfx subwindow- 
based program to SunView. spheres is explained in Appendix C, Converting 
SunWindows Programs to SunView, and is listed in full in in Appendix A, Exam¬ 
ple Programs. 
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Checking the Interval Timer 

The following function checks on the state of an interval timer by returning its 
current state in the structure pointed to by value. 

Notify_error 

notify_itimer_value(client, which, value) 

Notify_client client; 

int which; 

struct itimerval *value; 

Turning the Interval Timer Off 

If you specify an interval timer with its it_interval structure set to 
{0, 0}, the Notifier flushes any knowledge of the interval timer after it delivers 
the timeout notification. Otherwise, supplying a NULL interval timer pointer to 
notif y_set_itimer_f unc () will turn the timer off. 

17.5. Interposition 

SunView window objects utilize the Notifier for much of their communication 
and cooperation. The Notifier provides a mechanism called interposition, with 
which you can intercept control of the internal communications within SunView. 
Interposition is a powerful way to both monitor and modify window behavior in 
ways that extend the functionality of a window object. 

Interposition allows a client to intercept an event before it reaches the base event 
handler. The base event handler is the one set originally by a client. The client 
can call the base event handler before or after its own handling of the event, or 
not at all. Clients may use interposition to monitor and filter events coming in to 
an event handler and/or to modify a series of actions based on the results of some 
calculation. 

How Interposition Works 

A client requests that the Notifier install an interposer function, supplied by the 
client, for a specified client and type of event. When an event arrives, the 

Notifier calls the function at the top of the wait list for that client and that type of 
event. An interposed routine may (indirectly) call the next function in the inter¬ 
position sequence and receive its results. 

Figure 17-2 illustrates the flow of control with interposition. Note that the inter¬ 
poser could have stopped the flow of control to the base event handler. 
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Figure 17-2 


Monitoring a Frame’s State 



Example: Interposing on 
Open/Close 



Flow of Control in Interposition 



You can notice when a frame opens or closes by interposing in front of the 
frame’s client event handler. The client event handler is a SunView specific 
event handler which is built on top of the Notifier’s general client event mechan¬ 
ism." To install an interposer call the following routine: 

Notify_error 

notify_interpose_event_func(client, event_func, type) 
Notify_client client; 

Notify_func event_func; 

Notify__event_type type; 

client must be the handle of the Notifier client in front of which you are inter¬ 
posing. In SunView, this is the handle returned from window_create () . 10 ° 
type is always NOTIFY_SAFE for SunView clients. 


Let’s say that the application is displaying some animation, and wants to do the 
necessary computation only when the frame is open. It can use interposition to 
notice when the frame opens or closes. 

The program spheres (which shows one way to convert an old SunWindows gfx 
subwindow-based program to SunView) uses this technique to stop shading an 
image when its frame is closed. It is explained in Appendix C, Converting 
SunWindows Programs to SunView, and is listed in full in in Appendix A, Exam¬ 
ple Programs. 

Another example appears on the following page. Note the the call to 
notif y_next_event_f unc (), which transfers control to the frame’s client 
event handler through the Notifier. notif y_next_event_f unc () takes the 
same arguments as the interposer. 


99 The stream of events sent to a client event handler is described in in Chapter 6, Handling Input. 

100 It could also be the handle returned from the call to scrollbar create (). 
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♦include <suntool/sunview.h> 

static Notify__value my_frame_interposer () ; 


Frame frame; 

/* Create the frame */ 

frame = window_create(0, FRAME, 


0 ); 


/* Interpose in front of the frame's event handler */ 
(void) notify_interpose__event_func (frame, 

my__frame_interposer, NOT I FY_S AFE) ; 
/* Show frame and start dispatching events */ 
window_main___loop (frame) ; 

static Notify__value 

my_frame_interposer(frame, event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

int closed_initial, closed_current; 

Notify__value value; 

{ 

/* Determine initial state of frame */ 

closed_initial * (int) window_get(frame, FRAME_CLOSED); 

/* Let frame operate on the event */ 

value = notify_next_event_func(frame, event, arg, type); 
/* Determine current state of frame */ 

closed_current = (int) window_get(frame, FRAME_CLOSED); 

/* Change animation if states differ */ 
if (closed__initial != closed_current) { 
if (closed_current) { 

/* Turn off animation because closed */ 

(void) notify_set_itimer_func(me, my_animation, 

ITIMER_REAL, ITIMER_NULL, ITIMER_NULL); 

} else { 

/* Turn on animation because opened */ 

(void) notify__set__itimer_func (me, my_animation, 

ITIMER_REAL, &NOTIFY_POLLING_ITIMER, 
ITIMER_NULL); 

} 

} 

return (value); 

} 
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Discarding the Default Action 


In the example on the preceding page, you wanted the base event handler to han¬ 
dle the event (so that the frame gets closed/opened). If the interposed function 
replaces the base event handler, and you don’t want the base event handler to be 
called at all, your interposed procedure should not call 

not if y_next_event (). For example, your interposed function might han¬ 
dle scroll events itself, so you would not want the base event handler to perform 
an additional scroll. 


Interposing on Resize Events Another common use of interposition is to give your application more control 

over the layout of its subwindows. The code is very similar. You call 
notify_interpose_event_func () to interpose your event handler. In 
the event handler, the following fragment could be used: 

, 

value = notify_next_event_func(frame, event, arg, type); 
if (event_action(event) == WIN_RESIZE) 
resize(frame); 
return(value); 

s- J 


Let the default event handler handle the event, then check if the event is a resize 
event. If so, call your own resize () procedure to lay out the subwindows. 


NOTE 



A WIN_RESIZE event is not generated until the frame is resized. If you want 
your resize procedure to be called when the window first appears you must do so 
yourself. This is different from a canvas with the CANVAS_RESIZE attribute 
set, whose resize procedure is called the first time the canvas is displayed. 

If the user manually adjusts subwindow sizes using [ Control 1 -middle mouse but¬ 
ton, no WIN_RESIZE event is generated. You can disallow subwindow resizing 
by setting the FRAME_SubwiNDOWS_AD JUSTABLE attribute to FALSE. 


Example: resize demo The program resize demo shows how to achieve more complex window layouts 

than possible using window layout attributes. It is listed in Appendix A, Exam¬ 
ple Programs. 

Modifying a Frame’s Suppose an application must detect when the user selects the ‘Quit’ menu item in 

Destruction the frame menu, in order to perform some application-specific confirmation. We 

have to interpose in front of the frame’s client destroy event handler using the 
following routine. 

Notify_error 

notify_interpose_destroy__func (client, destroy_func) 
Notify_client client; 

Notify_func destroy_func; 

First, however, you need to understand client destroy events. 
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Destroy Events 


Checking 


Destruction 


A Typical Destroy Handler 


The Notifier can tell each client to destroy itself. It is possible for a destroy event 
handler to receive two calls concerning client destruction: one call may be a 
status inquiry and the other a demand for termination. Destroy event handlers 
use a status code to determine whether the caller demands actual termination 
(DESTROY_CLEANUP or DESTROY_PROCESS_DEATH), or simply requires an 
indication if it is feasible for the client to terminate at present 
DESTROY_CHECKING). 

If the status argument indicates an inquiry and the client cannot terminate at 
present, the destroy event handler should call not if y_veto_destroy (), 
indicating that termination would not be advisable at this time, and return nor¬ 
mally. If the status argument indicates an inquiry and the client can terminate 
at present, then the destroy handler should do nothing; a subsequent call will tell 
the client to actually destroy itself. 

This veto option is used, for example, to give a text subwindow the chance to ask 
the user to confirm the saving of any editing changes when quitting a tool. 

If the status argument is not DESTROY_CHECKlNG then the client is being 
told to destroy itself. If status is DESTROY_PROCESS_DEATH then the 
client can count on the entire process dying and so should do whatever it needs to 
do to cleanup its outside entanglements, e.g., update a file used by other 
processes. Since the entire process is dying, one might choose to not release all 
the resources used within the process, e.g., dynamically allocated memory. 
However, if status is DESTROY_CLEANUP then the client is being asked to 
destroy itself and be very tidy about cleaning up all the process internal resources 
that it is using, as well as its outside entanglements. 


A typical destroy handler looks like the following: 


Notify_value 

common_destroy__func (client f status) 

Notify_client client; 

Destroy_status status; 
if (status == DESTROY_CHECKING) { 

if (/* Don't want to go away now */) 
notify_veto_destroy(client); 

} else { 

/* Always release external commitments */ 
if (status -- DESTROY_CLEANUP) 

/* Conditionally release internal resources */ 

} 

return (NOTIFY_DONE); 
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Example: Interposing a Client 
Destroy Handler 

Now we can present the example of interposing in front of the frame’s client des¬ 
troy event handler. In addition to doing our own confirmation, we prevent dou¬ 
ble confirmation by suppressing the frame’s default confirmation. 

Note that after having the destroy OK’d by the user, we call 
notify_next_destroy_func () before returning. This allows other 
subwindows to request confirmation. 

The code appears on the following page. 


W sun 

\r microsystems 


Revision A, of May 9, 1988 




302 SunView 1 Programmer’s Guide 


#include <suntool/sunview.h> 

static Notify_value my_frame_destroyer(); 

/* 

* Interpose in front of the frame's destroy event handler 
*/ 

(void) notify__interpose_destroy_func (frame, 

my_frame_destroyer) ; 

/* Show frame and start dispatching events */ 
window_main_loop(frame); 


static Notify_value 

my_frame_destroyer(frame, status) 

Frame frame; 

Destroy_status status; 

if (status — DE STROY_CHECKING) { 

if (my internal state requires confirmation) { 

/* 

* Request confirmation from the user 

* (see window_loop() in the index) . 

*/ 


if ( destroy OK’d by user) { 

/* Tell frame not to do confirmation */ 
window_set(frame, FRAME_NO_CONFIRM, TRUE, 0); 
} else { 

/* 

* Tell the Notifier that the destroy has 

* been vetoed. 

*/ 

(void) notify_veto_destroy (frame) ; 

/* 

* Return now so that the destroy event 

* never reaches the frame's destroy handler. 
*/ 

return (NOTIFY_DONE); 

} 

} else { 

/* Let frame do normal confirmation */ 
window_set (frame, FRAME_NO_CONFIRM, FALSE, 0) ; 

} 

} 

/* Let frame get destroy event */ 

return (not if y__next_destroy_func (frame, status)); 

} 
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17.6. Porting Programs to Most programs that are ported to SunView are not notification-based. They are 
SunView traditional programs that maintain strict control over the inner control loop. 

Much of the state of such programs is preserved on the stack in the form of local 
variables. The Notifier supports this form of programming so that you can use 
SunView packages without inverting the control structure of your program to be 
notification-based. 

Explicit Dispatching The simplest way to convert a program to coexist with the Notifier is called 

explicit dispatching. This approach replaces the call to 

window_main_loop (), which usually doesn’t return until the application ter¬ 
minates, with the following bit of code: 


r 

♦include <suntool/sunview.h> 

\ 

static int my_done; 


extern Notify_error notify_dispatch() 

/ 

/* Make the frame visible on the screen */ 
window_set(frame, WIN_SHOW, TRUE, 0); 
while (!my_done) { 

/* Dispatch events managed by 
(void) notify__dispatch () ; 

the Notifier */ 

} 

v_ 

-j 


notif y_dispatch () goes once around the Notifier’s internal loop, 
dispatches any pending events, and returns. You should try to have 
notif y_dispatch () called at least once every 1/4 second so that good 
interactive response with SunView windows can be maintained. 

The program bounce (which shows one way to convert an old Sun Windows gfx 
subwindow-based program to SunView) uses explicit dispatching. It is 
explained in Appendix C, Converting SunWindows Programs to SunView, and is 
given in full in in Appendix A, Example Programs. 

Implicit Dispatching Explicit dispatching is good when you are performing some computationally 

intensive processing and you want to occasionally give the user a chance to 
interact with your program. There is another method of interacting with the 
Notifier that is useful when you simply want the Notifier to take care of its clients 
and block until there is something of interest to you. This is called implicit 
dispatching. 

This time, we replace the call to window_main_loop () with the following 
bit of code: 
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♦include <suntool/sunview.h> 

static int my_done; 

window_set(frame, WIN_SHOW, TRUE, 0) ; 

/* Enable implicit dispatching */ 

(void) notify_do_dispatch(); 
while (!my_done) { 
char c; 

/* read allows implicit dispatching by Notifier */ 
if ((n = read(0/*stdin*/, &c, 1)) < 0) 
perror("my_program"); 

} 

S_/ 


not if y_do_dispatch () allows the Notifier to dispatch events from within 
the calls to read(2) or select(2). The Notifier’s versions of read(2) and 
select (2) won’t return until the normal versions would. They can block 
exactly like the normal versions. 

not if y_no_dispat ch () (it takes no arguments) prevents the Notifier from 
dispatching events from within the call to read(2) or select(2). 

Getting Out When you use either of these dispatching approaches, you will need to find out 

when the frame is ‘Quit’ by the user, in order to know when to terminate your 
program. To do so, interpose in front of the frame’s destroy event handler, as in 
the previous section, so that you can notice when the frame goes away. At this 
point you can call notif y_stop () to break the read(2) or select(2) out 
of a blocking state. 
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17.7. Error Handling 
Error Codes 


Handling Errors 


--— > 

♦include <suntool/sunview.h> 

static int my_done; 

static Notify_value my_notice_destroy (); 

/* 

* Interpose in front of the frame's destroy event handler 
*/ 

(void) notify__interpose_destroy_func (frame, 

my_notice_destroy) ; 

static Notify_value 
my_notice_destroy(frame, status) 

Frame frame; 

Destroy_status status; 

if (status !— DESTROY_CHECKING) { 

/* Set my flag so that I terminate my loop soon */ 
my_done = 1; , 

/* Stop the notifier if blocked on read or select */ 
(void) notify_stop(); 

} 

/* Let frame get destroy event */ 

return (not if y_next__destroy_func (frame, status)); 

s_ J 


Every call to a notifier routine returns a value that indicates success or failure. 
Routines that return an enumerated type called Notif y_error deliver 
N0TIFY_0K (zero) to indicate a successful operation, while any other value 
indicates failure. Routines that return function pointers deliver a non-null value 
to indicate success, while a value of N0TIFY_FUNC_NULL indicates an error 
condition. 

When an error occurs, the global variable not if y_errno describes the failure. 
The Notifier sets not if y_errno much like UNIX system calls set the global 
errno; that is, the Notifier only sets not if y_errno when it detects an error 
and does not reset it to notify_OK on a successful operation. A table in the 
SunView 1 System Programmer’s Guide lists each possible value of 
notify_errno and its meaning. 

Most of the errors returned from the Notifier indicate a programmer error, e.g., 
the arguments are not valid. Often the best approach for the client is to print a 
message if the return value is non-zero and exit. The procedure 
notif y_perror () takes a string which is printed to stderr, followed by a 
colon, followed by a terse description of notif y_errno. This is done in a 
manner analogous to the UNIX perr or(3) call. 
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Debugging Here are some debugging hints that may prove useful when programming: 

NOT IF Y_ERROR_ABORT Setting the environment variable NOTlFY_ERROR_ABORT to YES will cause 

the Notifier to abort with a core dump when the Notifier detects an error. This is 
useful if there is some race condition that produces notifier error messages that 
you are having a hard time tracking down. 


Stop in not if y_j>error () If you are getting notifier error messages, but don’t know from where, try putting 

or fprintf (3S) a break point on the entry to either not if y_perror () or f printf (3S). 

Trace the stack to see what provoked the message. 


not if y_dump The following call can be made from the debugger or your program to dump a 

printout of the state of the Notifier: 

void 

notify_dump(client, type, file) 

Notify_client client; 
int type; 

FILE *file; 

The state of client is dumped to file based on the value of type. If 
client is 0 then all clients are dumped. If type is 1 then all the registered 
event handlers are dumped. If type is 2 then all the events pending for delivery 
are dumped. If type is 3 then both the registered event handlers and the events 
pending for delivery are dumped. If f ile is 1 then stdout is assumed. If f ile 
is 2 then stderr is assumed. To be able to call notif y_dump () you need to 
reference it from some place in your program so that it gets loaded into your 
binary. 



Revision A, of May 9,1988 






Attribute Utilities 


Attribute Utilities. 309 

18.1. Character Unit Macros. 309 

18.2. Creating Reusable Attribute Lists. 310 

Default Attributes. 311 

18.3. Maximum Attribute List Size. 311 





























Attribute Utilities 


This chapter describes macros and functions that are provided as utilities to be 
used with attributes. 

18.1. Character Unit By default in SunView, coordinate specification attributes interpret their values 

Macros in pixel units. For applications that don’t make heavy use of images, it is usually 

more convenient to specify positions in character units — columns and rows 
rather than xs and ys. To this end two macros ATTR_ROW () and ATTR_COL () 
are provided, which interpret their arguments as rows or columns, respectively, 
and convert the value to the corresponding number of pixels, based on the 
subwindow’s font, as specified by WIN_F0NT. ATTR_ROW () and 
ATTR__COL () take as arguments any expression yielding an integer. The use of 
these macros as an operand in an expression is restricted to adding a pixel offset 
(e.g., ATTR_ROW(5) + 2). Examples of legal and illegal usage are given in the 
table below. 


Table 18-1 


Example uses of the ATTR_ROW() and ATTR_COL() macros 


Attribute/Value 


PANE L_ITEM_X, 5 

PANEL_ITEM_Y, 10 

PANEL_ITEM_X, ATTR_COL(5) 

PANEL_ITEM__X, ATTR_COL (-5) 

PANEL_ITEM_X, ATTR_COL (5+2) 

PANEL_ITEM_X, ATTR_COL (5) +2 
PANEL__I TEM_X, ATTR_COL (5) -1 
PANEL_I TEM_Y, ATTR_ROW (10) 

PANEL_ITEM_Y, ATTR_ROW (-10) 

PANEL_ITEM_Y, ATTR_ROW (10+2) 

PANEL_ITEM_Y, ATTR_ROW(10)+2 
PANEL_ITEM_Y, ATTR_ROW(10)-1 
PANEL_ITEM_X, ATTR_COL(10)+ATTR_COL(2) 
PANEL_ITEM_X f 2*ATTR COL(10) 


Interpretation 
5 pixels from left 
10 pixels from top 
column 5 
column -5 
column 7 

2 pixels to right of col 5 

1 pixel to left of col 5 
row 10 

row -10 
row 12 

2 pixels down from row 10 
1 pixel up from row 10 
illegal 

illegal 


NOTE ATTR_ROW () and ATTR_COL () treat their arguments as character positions 
rather than lengths. In other words, when you use attr_row(5), the pixel 
value that is computed includes the top margin. Similarly, the pixel value com¬ 
puted using ATTR_COL(5) includes the left margin. 
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These macros can be used with the panel attributes or the window attributes such 
as WIN_X, WIN_HEIGHT, etc. 

Both the attributes and the ATTR_ROW () and ATTR_COL () macros are zero- 
based — that is, the first row is row zero. 

If you want to use lengths rather than positions, you can use the alternate macros 
ATTR_ROWS () and ATTR_COLS (). Examples of the differences between the 
character position and length macros are given in the table below. 

Table 18-2 Example uses of the ATTR_ROWS() and ATTR_COLS() macros 


Attribute/Value 

Interpretation 

WIN_WIDTH, ATTR_COL(80) 

80 characters wide + left margin 

WIN_WIDTH, ATTR_COLS(80) 

exactly 80 characters wide 

WIN_HEIGHT, ATTR_ROW(24) 

24 lines high + top margin 

WIN_HEIGHT, ATTR_ROWS(24) 

exactly 24 lines high 

PANEL_ITEM_X, ATTR_COL(5) 

col 5 (left margin + 5 character widths) 

PANEL_ITEM_X, ATTR_COLS(5) 

5 character widths from the left edge 

PANEL_ITEM_Y, ATTR_ROW(5) 

row 5 (top margin + 5 row heights) 

PANEL_ITEM_Y, ATTR_ROWS(5) 

5 row heights from the top edge 


18.2. Creating Reusable You may want to create an attribute list that can be passed to different routines. 

Attribute Lists You can do this either by creating the list explicitly, or by using the routine 

attr create list(). 


To create an attribute list explicitly, define a static array of char *, which is 
initialized (or later filled in with) the desired attribute/value pairs. Note that 
non-string values must be coerced to type char *: 


r 


static char ^attributes[] = { 

(char*)PANEL_LABEL_STRING, 

"Name: ", 

(char*)PANEL_VALUE, 

"Goofy ", 

(char*)PANEL_NOTIFY_PROC, 

(char *)name_item_proc. 

0 } 

V__ _ 

__y 


To make an attribute list dynamically, use: 

Attr_avlist 

attr_create_list(attributes) 

<attribute-list> attributes; 

attr_create_list () allocates storage for the list it returns. It is up to you 
to free this storage when no longer needed, as in: 
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Attr_avlist list; 

list = attr_create_list(PANEL_LABEL_BOLD, TRUE, 0); 
free(list); 

--- t 


The free () procedure is the standard UNIX free(3) routine. 

Default Attributes The code below shows how to use attr_create_list () in conjunction 

with the attribute ATTR_LIST to support default attributes in a panel. 


/— 

int 

Panel_item 

text_proc() f name_proc(); 
name_item, address_item; 


\ 


Pixfont 

*big_font, *small_font; 




Attr_avlist 

defaults; 




defaults = 

attr__create_list ( 





PANEL_SHOW_I TEM, 

FALSE, 




PANE L__LABE L__F ON T, 

big_font. 




PANEL_VALUE_FONT, 

small_font. 




PANEL NOTIFY PROC, 
0); 

text_j?roc. 



name_ji.tem = 

panel_create_item(PANEL_TEXT, 





ATTR_JLIST, 

defaults. 




PANEL NOTIFY PROC, 
0); 

name proc. 



addres s_item 

= panel_create_item(PANEL TEXT, 





ATTR_LIST, 

defaults. 




PANEL_SHOW_ITEM, 

TRUE, 


S 


PANEL VALUE FONT, 

0); 

big_font. 

j 


The special attribute ATTR_LIST takes as its value an attribute list. In the 
above example, first an attribute list called defaults is created. Then, by 
mentioning defaults first in the attribute lists for subsequent item creation 
calls, each item takes on those default attributes. Subsequent references to an 
attribute override the setting in defaults since the last value mentioned for an 
attribute is the one which takes effect. 


18.3. Maximum Attribute The maximum length of attribute-value lists supported by the SunView packages 
List Size (see ATTR_STANDARD_SIZE in <sunwindow/attr . h>) is 250. If the 

number of attributes in a list you pass to SunView exceeds this size, the attribute 
package prints 



on standard output and exits with exit status 1. 


V microsystems 


Revision A, of May 9,1988 

























SunView Interface Summary 


SunView Interface Summary... 315 

Alert Tables. 316 

Attributes. 3 16 

Functions. 318 

Canvas Tables. 319 

Attributes. 319 

Functions and Macros. 320 

Cursor Tables. 321 

Attributes. 321 

Functions. 323 

Data Types. 324 

Icon Tables. 328 

Attributes. 328 

Functions and Macros. 329 

Input Event Tables. 339 

Event Codes. 339 

Event Descriptors. 333 

Input-Related Window Attributes. 334 

Menu Tables. 335 

Attributes. 335 

Item Attributes. 339 

Functions. 341 

Notifier Functions Table. 343 

































Notifier Functions Table. 343 

Panel Tables. 346 

Attributes. 346 

Generic Panel Item Attributes. ' . 347 

Choice and Toggle Item Attributes. 349 

Slider Item Attributes... 351 

Text Item Attributes. 352 

Functions and Macros. 353 

Pixwin Tables . 356 

Pixwin Drawing Functions and Macros Table. 356 

Pixwin Color Manipulation Functions Table. 360 

Attributes. 362 

Functions and Macros. 365 

Text Subwindow Tables. 366 

Attributes. 366 

Textsw_action Attributes. 370 

Textsw_status Values. 371 

Functions... 372 

TTY Subwindow Tables. 376 

Attributes. 376 

Functions. 376 

Special Escape Sequences. 377 

Window Tables. 379 

Attributes. 379 

Frame Attributes. 382 

Functions and Macros. 384 

Command Line Frame Arguments. 386 


































SunView Interface Summary 


This chapter contains tables summarizing the data types, functions and attributes 
which comprise the SunView programmatic interface. 101 

The tables correspond to the chapters in this book, but are in alphabetical order: 
Alerts, Canvases, Cursors, Data Types, Icons, Input (including events and input- 
related window atttributes), Menus, the Notifier, Panels, Pixwins, Scrollbars, 
Text Subwindows, TTY Subwindows and Windows (including frames and frame 
command line arguments). 

Note that the order of the chapters is different than the order of the tables. The 
chapter on windows (including frames) comes first, followed by canvases, input, 
pixwins, text subwindows, panels, alerts, tty subwindows, menus, cursors, icons, 
scrollbars, the Selection Service, and the Notifier. 

Within each topic, the attribute tables come first, then the functions and macros, 
then miscellaneous tables. 

To help distinguish where one table ends and another begins, the start of each 
table is marked with a horizontal grey bar. 


101 This chapter does not include a table for the Selection Service functions; see the SunView System 
Programmer’s Guide for a complete discussion of the Selection Service interface. 
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Table 19-1 Alert Attributes 



Attribute 

Type 



Description 

ALERT_BUTTON 

char *, int 

A string to be displayed in a button and a value to associate with it The 
value specified with the string will be returned when the button is 
selected. The value may be any integer, but should not be a value 
predefined by the alerts package; that is, not ALERT_YES, ALERT_NO, 
ALERT_FAILED, or ALERT_DEFAULT_TRIGGERED). 

See the values given in the Alert Functions table. 

ALERT_BOTTON_FONT 

Pixfont * 

Font used for buttons. Default is the font specified for menus, which is 
Menu!Font in defaultsedit or screen. b. 14 if no default is specified. 

ALERT_BUTTON_NO 

char * 

A string that is associated with the accelerated 

NO (cancel, don’t do it) button which is triggered via a 
keyboard accelerator. The value returned if this button is selected 
(or the accelerator is triggered) will be ALERT_NO. Only one instance 
of this attribute is allowed. 

ALERT_BUTTON_YES 

char * 

A string to associate with the accelerated 

YES (ie. confirm, continue, do it) button which is also triggered via a 
keyboard accelerator. The value returned when this button is selected 
(or the accelerator is triggered) will be ALERT_YES. Only one instance 
of this attribute is allowed. 

ALERT_MESSAGE_FONT 

Pixfont * 

Font used for message strings. 

The default is the same as Client Frame (if specified) otherwise it is the 
same as SunView/Font. 

ALERT_MESSAGE_STRINGS 

list char* 

Strings to be displayed in the message 

area of the alert panel. The default is to be determined. 

ALERT_MES SAGE_STRINGS_ARRAY_P TR 

array char* 

Same as ALERT_MESSAGE_STRINGS 

except the client need not know the actual strings being passed, just 
that the value is pointer to first of null terminated array of strings. 

The alerts package will cast the value into a type char **. 

ALERT_N 0_BEEPING 

int 

Allows the client to specify that no beeping should 
take place reguardless of defaults database setting. The default for this 
option is FALSE; that is, beep however many times database specifies. 
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Table 19-1 

Alert Attributes — Continued 


Attribute 

Type 

Description 

ALERT 

_OPTIONAL 

boolean 

Specifies whether an optional alert will be enabled 
or disabled. You make an alert a 
courtesy alert by specifing the ALERT_OPT IONAL 
attribute in the attribute list passed to 
alert_prompt (). 

ALERT_ 

POSITION 

int 

Specifies the position of the alert. 

Default is ALERT_CLIENT_CENTERED unless client_frame = NULL 
NULL causes the alert to default to ALERT_SCREEN_CENTERED 
regardless of this setting. 




Possible values that may be passed are: ALERT_SCREEN CENTERED, 
ALERT_CLIENT_CENTERED, and ALERT_CLIENT_OFFSET. 

Use WIN_X and WIN_Y for the offset attributes. This position describes 
where the “center” of an alert should be. 

ALERT_ 

TRIGGER 

int 

This special attribute allows the client to 

specify a SunView event which should cause the alert to return. The 
default is not to return unless an actual button has been selected 
or the other YES/NO accelerators are seen. When this event is triggered, 
the value returned will be ALERT__TRIGGERED. 
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Table 19-2 Alert Functions 



Definition Description 


int 

alert_prompt(client frame, event, attributes) 
Frame client__f rame; 

Event *event; 

<attribute-list> attributes; 


Displays alert and doesn’t return until the user pushes a 
button, or its trigger or the default has been seen. A value 
of ALERT_FA I LED is returned if alert_prompt () 
failed for any reason, otherwise equivalent to ordinal value 
of button which caused return (ie. button actually selected, 
or default button if default action triggered return). The 
client_frame may be NULL (see ALERT_P0SITI ON for 
consequences). The event will be completely filled in at 
the time the alert_prompt () returns. 

The possible status values that may be returned from this 
function are: the (int) value passed with every 
ALERT_BUTTON attribute; ALERT_YES, if a confirm but¬ 
ton or trigger was pushed; ALERT_NO, if a cancel button or 
trigger was pushed; ALERT_FAILED, if the alert failed to 
pop up; and ALERT_TRIGGERED, if a keyboard accelera¬ 
tor was used. 


* 
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Table 19-3 Canvas Attributes 


Attribute 

Type 

. . '■. . . . . . . . ... . . .......... | 

Description 

CANVAS_AUT 0_CLEAR 

boolean 

If TRUE, repaint area of canvas pixwin is cleared before, 
repaint proc is called. Default: TRUE unless the canvas is retained. 

CANVAS_AUTO_EXPAND 

boolean 

If TRUE, canvas width and height are never allowed to be 
less than the edges of the canvas pixwin. Default: TRUE. 

CANVAS__AUTO_SHRI NK 

boolean 

If TRUE, canvas width and height are never allowed to be 
greater than the edges of the canvas pixwin. Default: TRUE. 

CANVAS_FAST_MONO 

boolean 

If TRUE, tells canvases and graphics sub windows to use 

the monochrome overlay plane of the Sun-3/110 display. Default: FALSE. 

CANVAS_FIXED_IMAGE 

boolean 

If TRUE, canvas package assumes that client is drawing a fixed-size image 
whose rendering does not depend on the size of the canvas. Default: TRUE. 

CANVAS_HEIGHT 

int 

Height of object being drawn. Default: height of usable window, which is 
WIN_HEIGHT - (SCROLL_THICKNESS of WIN_HORIZONTAL_SCROLLBAR) - 
CANVAS_MARGIN*2. 

CANVAS_MARGIN 

int 

Margin to leave around the canvas pixwin from inside of window. Default: 0. 

CANVAS_PIXWIN 

Pixwin * 

Pixwin for drawing. Get only. 

CANVAS_REPAINT__PROC 

(procedure) 

Called when repaint needed, even if retained. Default: NULL. Form: 
repaint_proc(canvas, pixwin, repaint_area) 

Canvas canvas; 

Pixwin *pixwin; 

Rectlist *repaint area; 

CANVAS_RESIZE_PROC 

(procedure) 

Called when canvas width or height changes. Default: NULL. Form: 
resize_proc(canvas, width, height) 

Canvas canvas; 

int width; 
int height; 

CANVAS_RETAINED 

boolean 

If TRUE, image is backed up for repaint. Default: TRUE. 

CANVAS_WIDTH 

int 

Width of object being drawn. Default: width of usable window, which is 

WIN_WIDTH - (SCROLLJTHICKNESS of WIN_VERTICAL_SCROLLBAR) - 
CANVAS_MARG I N*2. 
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Table 19-4 Canvas Functions and Macros 




microsystems 


Revision A, of May 9, 1988 












Chapter 19 — SunView Interface Summary ( Cursor Attributes) 321 


Table 19-5 Cursor Attributes 


Attribute 

Value Type 

Description 

C0RS0R_CR0SSHAIRJ30RDER_GRAVITY 

boolean 

Crosshairs stick to borders. Default: FALSE. 

CURSOR_CROSSHAIR_COLOR 

int 

Color for crosshairs. Default: 1. (Note: the color displayed 
depends on the settings in your colormap segment). 

CURSOR_CROSSHAIR_GAP 

int 

Half-length of space to leave untouched from intersection of 
crosshairs. Value of CURSOR_TO_EDGE extends crosshairs to 
edge of cursor rect Default: 0. 

CURSOR_CROSSHAIR_LENGTH 

int 

Half-length of crosshairs. Default: CURSOR TO EDGE. 

CURSOR_CROSSHAI R__OP 

int 

Raster op for drawing crosshairs. Default: PIX__SRC. 

CURSOR_CROSSHAIRJTHICKNESS 

int 

Thickness of crosshairs. Maximum value is 

CURSOR_MAX_HAIR_THICKNESS (5). Default: 1. 

CURSOR_FULLS CREEN 

boolean 

Clip crosshairs to edge of screen not window. Default: FALSE. 

CURSOR_HORIZ_HAIR_BORDER_GRAVI TY 

boolean 

Horizontal crosshair sticks to borders. Default: FALSE. 

CURSOR_HORIZ_HAIR_COLOR 

int 

See CURSOR_HORI Z__HAIR__COLOR 

CURS OR_HOR I Z_HA I R__GAP 

int 

See CURSOR_CROSSHAIR_GAP. 

CURSOR_HORIZ_HAIR_LENGTH 

int 

See CURSOR_CROSSHAIR__LENGTH. 

CURSOR_HORI Z_HAIR_OP 

int 

Raster op for drawing horizontal crosshair. Default: PIX SRC. 

CURSOR_HORIZ_HAIR_THICKNESS 

int 

See CURSOR_CROSSHAIR__THICKNESS. 

CURS OR_IMAGE 

Pixrect * 

Cursor’s image. Default: 16x16x1 blank pixrect. 

CURSOR_OP 

int 

Raster op for drawing cursor image. 

Default: PIX_SRC | PIX_DST. 

CURSOR_SHOW_CROSSHAIRS 

boolean 

Show or don’t show crosshairs. Default: FALSE. 

CURSOR_SHOW_CURSOR 

boolean 

Show or don't show cursor image. Default: TRUE. 

CURSOR_SHOW_HORIZ_HAIR 

boolean 

Show or don’t show horizontal crosshair. Default: FALSE. 

CURSOR_SHOW_VERT_HAIR 

boolean 

Show or don’t show vertical crosshair. Default: FALSE. 
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Table 19-5 Cursor Attributes—Continued 

Attribute Value Type _ Description _ 

Vertical crosshair sticks to borders. Default: FALSE. 


CURSOR VERT HAIR BORDER GRAVITY 

boolean 

CURSOR_VERT_HAIR_COLOR 

int 

CURSOR_VERT_HAIR_GAP 

int 

CURSOR_VERT_HAI R__LENGTH 

int 

CURSOR_VERT_HAI R_OP 

int 

CURSOR_VERT_HAI R_THICKNESS 

int 

CURS OR_XHOT 

int 

CURSOR YHOT 

int 


See CURSOR_CROSSHAIR_COLOR 
See CURSOR_CROSSHAIR_GAP. 

See CURSOR_CROSSHAIR_LENGTH. 

Raster op for drawing vertical crosshair. Default: PIX_SRC. 
See CURSOR_CROSSHAIR_THICKNESS. 

Hot spot x coordinate. Default: 0. 

Hot spot y coordinate. Default: 0. 
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Table 19-6 Cursor Functions 


Definition 

Description 

Cursor 

cursor__copy (src cursor) 

Cursor src_cursor; 

Creates and returns a copy of src cursor. 

Cursor 

cursor_create(attributes) 

<attribute-list> a11 ribute s; 

Creates and returns the opaque handle to a cursor. 

void 

cursor_destroy(cursor) 

Cursor cursor; 

Destroys cursor. 

caddr_t 

cursor_get(cursor, attribute) 

Cursor cursor; 

Cursor__attribute attribute; 

Retrieves the value for an attribute of cursor. 

void 

cursor__set (cursor, attributes) 

Cursor cursor; 

<attribute-list> attributes; 

Sets the value for one or more attributes of cursor. 

attributes is a null-terminated attribute list. 
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Table 19-7 

Data Types 



Data Type 

Description 

Canvas 

Pointer to an opaque structure which describes a canvas. 

Cursor 

Pointer to an opaque structure which describes a cursor. 

Destroy_status 

Enumeration: DESTROY_PROCESS_DEATH, 

DESTROY_CHECKING, or DESTROY_CLEANUP. 

Event 

The structure which describes an input event: 
typedef struct inputevent { 
short ie_code; 
short ie__flags; 
short ie_shiftmask; 
short ie_locx; 
short ie__locy; 
struct timeval ie_time; 

} Event; 

Frame 

Pointer to an opaque structure which describes a frame. 

Icon 

Pointer to an opaque structure which describes a icon. 

Inputmask 

Mask specifying which input events a window will receive. 

Menu 

Pointer to an opaque structure which describes a menu. 

Menu_at.tr ibute 

One of the menu attributes (MENU_*). 

Menu_generate 

Enumerated type of the operation parameter passed to generate procs: 

MENU CREATE, MENU DESTROY, MENU_NOTIFY_CREATE or MENU_NOTIFY_DESTROY. 

Menu item 

Pointer to an opaque structure which describes a menu item. 

Notify_arg 

Opaque client optional argument. 

Notify_destroy 

Enumeration: NOT I FY_SAFE, NOT I FY__I MMEDI ATE. 

(See also Notify_event_type). 

Notify_event 

Opaque client event. 
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Table 19-7 

Data Types — Continued 

Data Type 

Description 

Notify_error 

Enumeration of errors for notifier functions: 

NOTIFY_OK, NOTIFY_UNKNOWN_CLIENT, NOTIFY_NO_CONDITION, 

NOTIFY_BAD_ITIMER, NOTIFY_BAD_SIGNAL, NOTIFY_NOT_STARTED, 
NOTIFY_DESTROY_VETOED, NOTIFY_INTERNAL_ERROR, NOTIFY_SRCH, 
NOTIFY_BADF, NOTIFY_NOMEM, NOTIFY_INVAL, or NOTIFY_FUNC_LIMIT. 

Notify_event type 

Enumeration: NOTIFY_SAFE, NOTIFY_IMMEDIATE. 

Notify func 

Notifier function. 

Notify_signal_mode 

Enumeration: NOTIFY_SYNC, NOTIFY_ASYNC. 

Notify_value 

Enumeration of possible return values for client notify procs: 

NOTIFY_DONE, NOTIFY_IGNORED, or NOTIFY_UNEXPECTED. 

Panel 

Pointer to an opaque structure which describes a panel. 

Panel_attribute 

One of the panel attributes (PANEL *). 

Panel_item 

Pointer to an opaque structure which describes a panel item. 

Panel_setting 

Enumerated type returned by panel_text_not ify (); 
also type of repaint argument to panel_paint (). 

See the Panels chapter and <suntool/panel. h>. 

Pixfont 

The structure representing a font (for definition see the Pixrect Reference Manual). 

Pixrect 

The basic object of pixel manipulation in the SunView window system. Pixrects 
include both a rectangular array of pixels and the means of accessing operations 
for manipulating those pixels (for definition see the Pixrect Reference Manual). 

Pixwin 

The basic imaging element of the SunView window system. While, for 
historical reasons, its fields are public, clients should treat it as an opaque handle. 

Rect 

The structure describing a rectangle: 
typedef struct rect { 
short r_left; 
short r__top; 
short r_width; 
short r_height; 

} Rect; 
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Table 19-7 

Data Types — Continued 

Data Type 

Description 

Rectlist 

A list of rectangles: 

typedef struct rectlist { 
short rl_x, rl_y; 

Rectnode *rl_head; 

Rectnode *rl_tail; 

Rect rl_bound; 

} Rectlist; 


typedef struct rectnode { 

Rectnode *rn_next; 

Rect rn_rect; 

} Rectnode; 

Scroll_motion 

Enumerated type representing possible scrolling motions: 

SCROLL_ABSOLUTE, SCROLL_FORWARD, SCROLL_MAX_TO_POINT, 
SCROLL_PAGE_FORWARD, SCROLL_LINE_FORWARD, 

SCROLL_BACKWARD, SCROLL_POINT_TO_MAX, 

SCROLL__P AGE_BACKWARD, or SCROLL_L I NE_BACKWARD. 

Scrollbar 

The opaque handle for a scrollbar. 

Scrollbar_attribute 

One of the scrollbar attributes (SCROLL_*). 

Scrollbar_setting 

The value of an enumerated type scrollbar attribute. 

Textsw 

Pointer to an opaque structure which describes a text subwindow. 

Text sw_index 

An index for a character within a text subwindow. 

Textsw enum 

Enumerated type for various text subwindow attribute values: 

TEXTSW_ALWAYS, TEXTSW_NEVER, TEXTSW_ONLY, 

TEXTSW_IF_AUTO__SCROLL, TEXTSW_CLIP, 

TEXTSW_WRAP_AT_CHAR, TEXTSW_WRAP_AT_WORD. 

Textsw_status 

Enumeration describing the status of text subwindow operations: 

TEXTSW ST AT U S_OKA Y, TEXT SW_ST ATU S_BAD_ATTR, 

TEXTSW ST AT U S_BAD_ATTR_VALUE, TEXT SW_ST ATU S_CANNOT_ALLOCATE, 

TEXTSW STATUS CANNOT_OPEN_INPUT, or TEXTSW_STATUS_OTHER_ERROR, 

Tty 

Pointer to an opaque structure which describes a tty sub window. 

Window 

Pointer to an opaque structure which describes a window. 
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Table 19-7 

Data Types — Continued 

Data Type 

Description 

Window_attribute 

One of the window attributes (WIN *). 

Window type 

Type of window, retrieved via the WIN TYPE attribute. One of: 

FRAME_TYPE, PANEL_TYPE, CANVASJTYPE, TEXTSW TYPE, or TTY TYPE. 
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Table 19-8 Icon Attributes 


Attribute 

Type 

Description 

ICON_FONT 

Pixfont * 

Font for icon’s label. 

ICON_HEIGHT 

int 

Icon’s height in pixels. Default: 64. 

ICON_IMAGE 

Pixrect* 

Memory pixrect for icon’s image. 

I CON__I MAGE_RE CT 

Rect * 

Rect for icon’s image. Default: origin (0,0), width 64, height 64. 

ICON_LABEL 

char * 

Icon’s label. 

ICON_LABEL_RECT 

Rect * 

Rect for icon’s label. Default: origin (0, 0), width 0, height 0. 

ICON_WIDTH 

int 

Icon’s width in pixels. Default: 64. 
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Table 19-9 Icon Functions and Macros 


Definition 

Description 

Icon 


icon_create(attributes) 

Creates and returns the opaque handle to an icon. 

<attribute-list> att ribut e s; 



int 

icon_destroy (icon) Destroys icon. 


Icon icon; 


caddr_t 

icon_get (icon, attribute) Retrieves the value for an attribute of icon. 

Icon icon; 

Icon_attribute attribute; 


int 

icon_set (icon, attributes) Sets the value for one or more attributes of icon. 

Icon icon; attributes is a null-terminated attribute list 

<attribute-list> attributes; 


extern static struct mpr_data Macro that creates a static memory pixrect 

DEFINE_ICON_FROM_IMAGE (name, image) icon from image; the latter typically is gen- 

static short icon_image [] ; erated by including a file created by iconedit. 

Note: you must pass the address of icon to the 
_icon routines, since the Icon object is a pointer. 
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Table 19-10 Event Codes 


Event Code 

Description 

Value (for debugging) 

ASCII_FIRST 

Marks beginning of ASCII range 

0 

ASCII LAST 

Marks end of ASCII range 

127 

META FIRST 

Marks beginning of META range 

128 

META_LAST 

Marks end of META range 

255 

ACTION ERASE CHAR BACKWARD 

Erase char to the left of caret 

31744 

ACTION ERASE CHAR FORWARD 

Erase char to the right of caret 

31745 

ACTION ERASE WORD BACKWARD 

Erase word to the left of caret 

31746 

ACTION ERASE WORD FORWARD 

Erase word to the right of caret 

31747 

ACTION ERASE LINE BACKWARD 

Erase to the beginning of the line 

31748 

ACTION_ERASE_LINE_END 

Erase to the end of the line 

31749 

ACTION GO CHAR BACKWARD 

Move the caret one character to the left 

31752 

ACTION GO CHAR FORWARD 

Move the caret one character to the right 

31753 

ACTION GO WORD BACKWARD 

Move the caret one word to the left 

31754 

ACTION GO WORD END 

Move the caret to the end of the word 

31756 

ACTION_GO_WORD_FORWARD 

Move the caret one word to the right 

31755 

ACTION_GO_LINE_BACKWARD 

Move the caret to the start of the line 

31757 

ACTION_GO_LINE_END 

Move the caret to the end of the line 

31759 

ACTION_GO_LINE_FORWARD 

Move the caret to the start of the next line 

31758 

ACTION_GO_COLUMN_BACKWARD 

Move the caret up one line, 
maintaining column position 

31761 

ACTION_GO_COLUMN_FORWARD 

Move the caret down one line, 
maintaining column position 

31762 

ACTION_GO_DOCUMENT_START 

Move the caret to the beginning of the text 

31763 

ACTION_GO_DOCUMENT_END 

Move the caret to the end of the text 

31764 

ACTION_STOP 

Stop the operation 

31767 

ACTION_AGAIN 

Repeat previous operation 

31768 

ACTION_PROPS 

Show property sheet window 

31769 

ACTION_UND0 

Undo previous operation 

31770 

ACTION_FRONT 

Bring window to the front of the desktop 

31772 

ACTION_BACK 

Put the window at the back of the desktop 

31773 

ACTION_OPEN 

Open a window from its icon form or close 
if already open) 

31775 

ACTION_CLOSE 

Close a window to an icon 

31776 

ACTION_COPY 

Copy the selection to the clipboard 

31774 

ACTION_PASTE 

Copy clipboard contents to the insertion point 

31777 

ACTION_CUT 

Delete the selection, put on clipboard 

31781 

ACTION_COPY_THEN_PASTE 

Copies then pastes text 

31784 

ACTION_FIND_FORWARD 

Find the text selection to the right of the caret 

31779 

ACTION_FIND_BACKWARD 

Find the text selection to the left of the caret 

31778 

ACTION_FIND_AND_REPLACE 

Show find and replace window 

31780 

ACTION SELECT FIELD FORWARD 

Select the next delimited field 

31783 
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Table 19-10 Event Codes — Continued 


Event Code 

Description 

Value (for debugging) 

ACTION_SELECT_FIELD_BACKWARD 

Select the previous delimited field 

31782 

ACTION_MATCH_DELIMITER 

Selects text up to a matching delimiter 

31894 

ACTI ON__QUOTE 

Causes next event in the input stream to 
pass untranslated by the keymapping system 

31898 

ACT10N_EMP TY 

Causes the sub window to be emptied 

31899 

ACTION_STORE 

Stores the specified selection as a new file 

31785 

ACTIONJLOAD 

Loads the specified selection as a new file 

31786 

ACTI ON_GET_F ILENAME 

Gets the selected filename 

31788 

ACTION_SET_DIRECTORY 

Sets the directory to the selection 

31788 

ACTION_INCLUDE_FILE 

Selects the current line (in pending-delete mode) 
and attempts to insert the file described by that selection 

31891 

ACTION_CAPS_LOCK 

Toggle caps lock state 

31895 

PANEL_EVENT_CANCEL 

The panel or panel item is no longer “current” 

32000 

PANEL_EVENT_MOVE_IN 

The panel or panel item was entered 
with no mouse buttons down 

32001 

PANEL_EVENT_DRAG_IN 

The panel or panel item was entered with one or more 
mouse buttons down 

32002 

SCROLL_REQUEST 

Scrolling has been requested 

32256 

SCROLL_ENTER 

Locator (mouse) has moved into the scrollbar 

32257 

SCROLL_EXI T 

Locator (mouse) has moved out of the scrollbar 

32258 

LOC_MOVE 

Locator (mouse) has moved 

32512 

LOC_STILL 

Locator (mouse) has been still for 1/5 second 

32513 

LOC_WINENTER 

Locator (mouse) has entered window 

32514 

LOC_WINEXIT 

Locator (mouse) has exited window 

32515 

LOC_DRAG 

Locator (mouse) has moved while a button was down 

32516 

LOC_RGNENTER 

Locator (mouse) has entered a region of the window 

32519 

LOC_RGNEXIT 

Locator (mouse) has exited a region of the window 

32520 

LOC_TRAJECTORY 

Inhibits the collapse of mouse motions; clients receive 
LOC_TRA JECTORY events for every locator motion 
the window system detects. 

32523 

WIN_REPAINT 

Some portion of window requires repainting 

32517 

WIN_RESIZE 

Window has been resized 

32518 

WIN_STOP 

User has pressed the stop key 

32522 

KBD_REQUEST 

Window is about to become the focus of keyboard input 

32526 

KBD_USE 

Window is now the focus of keyboard input 

32524 

KBD_DONE 

Window is no longer the focus of keyboard input 

32525 

SHIFT_LEFT 

Left shift key changed state 

32530 

SHIFT_RIGHT 

Right shift key changed state 

32531 

SHIFT_CTRL 

Control key changed state 

32532 

SHIFT_META 

Meta key changed state 

32534 

SHIFT JLOCK 

Shift lock key changed state 

32529 
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Table 19-10 Event Codes — Continued 


Event Code 

Description 

Value (for debugging) 

SHIFT_CAPSLOCK 

Caps lock key changed state 

32528 

BUT(i) 

Locator (mouse) buttons 1-10 

BUT(l) is 32544 

MS_LEFT 

Left mouse button 

32544 

MS_MIDDLE 

Middle mouse button 

32545 

MS_RIGHT 

Right mouse button 

32546 

KEY_LEFT(i) 

Left function keys 1-15 

KEY_LEFT (1) is 32554 

KEY_RIGHT(i) 

Right function keys 1-15 

KEY_RIGHT (1) is 32570 

KEYJTOP(i) 

Top function keys 1-15 

KEYJTOP (1) is 32586 
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Table 19-11 Event Descriptors 


Event Descriptor 

Explanation 

WIN_N0_EVENTS 

Clears input mask — no events will be accepted. Note: the 
effect is the same whether used with a consume or an 
ignore attribute. A new window has a cleared input mask. 

WIN_ASCII__E VENTS 

All ASCH events. ASCII events that occur while the META 
key is depressed are reported with codes in the META range. 

In addition, cursor control keys and function keys are 
reported as ANSI escape sequences: a sequence of events 
whose codes are ASCII characters, beginning with <ESC>. 

WI N_IN__TRAN SI T_E VENT S 

Enables immediate LOC_MOVE, LOC WINENTER, and 

LOC_WINEXIT events. Pick mask only. Off by default. 

WIN__LEFT_KEYS 

The left function keys, KEY_LEFT(1) — KEY_LEFT(15). 

WIN_MOUSE_BUTTONS 

Shorthand for MS_RIGHT, MS_MIDDLE and MS LEFT. 

Also sets or resets WIN_UP EVENTS. 

WI N_R I GHT_KE Y S 

The right function keys, KEY_RIGHT(1) — KEY_RIGHT(15). 

WI N__T OP_KE Y S 

The top function keys, KEY_TOP(l) — KEY_TOP(15). 

WIN_UP_ASCI I_EVENTS 

Causes the matching up transitions to normal 

ASCH events to be reported — if you see an V 
go down, you’ll eventually see the matching ’a’ up. 

WIN_UP_EVENTS 

Causes up transitions to be reported for button 
and function key events being consumed. 
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Table 19-12 Input-Related Window Attributes 



Attribute 

Value Type 

Description 

WIN_INPUT_DESIGNEE 

int 

Window which gets events this window doesn’t consume. 

(Note that the value must be the designee’s WIN_DEVICE_NUMBER). 

WI N_GRAB__ALL__INPUT 

boolean 

Window will get all events regardless of location. 

WIN_KBD_FOCUS 

boolean 

Whether or not the window has the keyboard focus. 

WIN_KBD_INPUT_MASK 

Inputmask * 

Window’s keyboard inputmask. 

WIN_PICK_INPUT_MASK 

Inputmask * 

Window’s pick inputmask. 

WIN_CONSUME_KBD_EVENT 

short 

Window will receive this event. 

WIN_IGNORE_KBD_EVENT 

short 

Window will not receive this event. 

WIN_CONSUME_KBD_EVENTS 

short list 

Null terminated list of events window will receive. 

WIN_IGNORE_KBD_EVENTS 

short list 

Null terminated list of events window will not receive. 

WIN_CONSUME_PICK_EVENT 

short 

Window will receive this pick event. 

WIN_IGNORE_PICK_EVENT 

short 

Window will not receive this pick event. 

WIN_CONSUME_PICK_EVENTS 

short list 

Null terminated list of pick events window will receive. 

WIN_IGNORE_PICK_EVENTS 

short list 

Null terminated list of pick events window will not receive. 
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Table 19-13 Menu Attributes 




Attribute 

Value Type 

Description 

MENU_ACTION_IMAGE 

Pixrect *, action proc 

Create image menu item with action proc. Set only. 

MENU_ACTION_ITEM 

char *, action proc 

Create string menu item with action proc. Set only. 

MENU_APPEND_ITEM 

Menu_item 

Append item to end of menu. Set only. 

MENUJ30XED 

boolean 

If TRUE, a single-pixel box will be drawn around 
every menu item. 

MENU_CENTER 

boolean 

If TRUE, all string items in the menu will be centered. Default: FALSE 

MENU_CLIENT_DATA 

caddr_t 

For client’s use. 

MENU_COLUMN_MAJOR 

boolean 

If TRUE, string items in the menu will be sorted in column-major 
order (like ls(l)) instead of row-major order. Default: FALSE 

MENU_CLIENT_DATA 

caddr_t 

For client’s use. 

MENU_DESCEND__FIRST 

(no value) 

For menu_f ind (). If given, search will 
be depth first, else search will be "deferred". 

MENU_DEFAULT 

int 

Default menu item as a position. 

MENU_DEFAULT__I TEM 

Menu_item 

Default menu item as opaque handle. 

MENU_DEFAULT_SELECTION 

enum 

Either MENU_SELECTED or MENU_DEFAULT. 

MENU_FIRST_EVENT 

Event * 

The event which was initially passed into 
menu_show (). Get only. 

(Note that the event’s contents can be modified.) 

MENU_FONT 

Pixfont * 

Menu’s font. 

MEN U_GEN_PROC 

(procedure) 

Client’s function called to generate the menu. 

Menu gen_proc(m, op) 

Menu m; 

Menu_generate op; 

MENU_GEN_P ULLRI GHT_I MAGE 

Pixrect *, gen proc 

Create image menu item with 
generate proc for pullright. Set only. 

MENU_GEN_PULLRIGHT_I TEM 

char *, gen proc 

Create string menu item with 
generate proc for pullright. Set only. 

MENU_IMAGE_ITEM 

Pixrect *, value 

Create image menu item with value. Set only. 
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Table 19-13 Menu Attributes— Continued 


Attribute 

Value Type 

Description 

MENU_IMAGES 

list of Pixrect * 

Create multiple image menu items. Set only. 

MENU_INITIAL_SELECTION 

enum 

Either MENU__SELECTED or MENU_DEFAULT. 

MENU INITIAL SELECTION EXPANDED boolean 

If TRUE, when the menu pops up, it 



automatically expands to select the initial selection. 

MENU INITIAL SELECTION_SELECTED boolean 

If TRUE, menu comes up with its initial 



selection highlighted. If FALSE, menu comes 



up with the cursor "standing off' to the left 

MENU_INSERT 

int, Menu_item 

Insert new item after nth item. Set only. 

MENU INSERT ITEM 

Menu_item, Menu_item The item given as the second value is inserted 



after the one given as the first value. Set only. 

MENU ITEM 

avlist 

Create a menu item inline — avlist same as for 



menu_create_item (). Set only. 

MENU_JUMP_AFTER_NO_SELECTION 

boolean 

If TRUE, cursor jumps back to its 



original position after no selection made. 

MENU_JUMP_AFTER_SELECTION 

boolean 

If TRUE, cursor jumps back to its 



original position after selection made. 

MENU_LAST_EVENT 

Event* 

The last event read by the menu. Get only. 



Note that the event’s contents can be modified. 

MENU_LEFT_MARGIN 

int 

For each string item, margin in addition to 



MENU MARGIN on left between menu’s 



border and text. Default: 16. 

MENU_MARGIN 

int 

Margin in pixels around menu items. Default: 1. 

MENU_NCOLS 

int 

Number of columns in menu. 

MENU_NITEMS 

int 

Get only; returns the # of items in the menu. 

MENU_NROWS 

int 

Number of rows in menu. 

MENU_NOTIFY_PROC 

(procedure) 

Client’s function called when the user selects 



a menu item. 



caddr_t notify_proc(m, mi) 



Menu m; 



Menu item mi; 
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Table 19-13 Menu Attributes — Continued 


Attribute 

Value Type 

Description 

MENU_NTH_ITEM 

int 

starting from 1. 

Get only; returns nth menu item, n is counted 

MENU__PARENT 

Menu_item 

The menu item for which the menu is a pullright. Get only. 

MENU_P ULLRIGHT_DELTA 

int 

Number of pixels the user must move the cursor 
to the right to cause a pullright menu to pop up. 

Default: 9999. 

MENUJP ULLRI GHT__I MAGE 

Pixrect *, Menu 

Create image menu item with pullright. Set only. 

MENU_P ULLRI GHT_I TEM 

char *, Menu 

Create string menu item with pullright Set only. 

MENU_REMOVE 

int 

Remove the nth item. Set only. 

MENU_REMOVE_ITEM 

Menu_item 

Remove the specified item. Set only. 

MENU_REP LACE 

int, Menu_item 

Replace nth item with specified item. Set only. 

MENU_REPLACE__I TEM 

Menu_item, Menu_item The item given as first value is replaced 
with the one given as the second value 
in the menu (the old item is not replaced 
in any other menus it may appear in). Set only. 

MENU_R I GHT_MARGI N 

int 

For each string item, margin in addition to 

MENU_MARGIN on right 
between menu’s border and text. 

MENU_SELECTED 

int 

Last selected item, as a position in menu. 

MENU_SELECTED_ITEM 

Menujtem 

Last selected item, as the item’s handle. 

MENU_SHADOW 

Pixrect * 

Pattern for the shadow to be painted behind 
the menu. If 0, no shadow is painted. 

Predefined shadow pixrects you can use: 
menu_gray25 _pr, menu__gray50_pr, 
and menu_gray 7 5_pr. 

MENU_STAY__UP 

boolean 

If TRUE the first click of the Menu button puts up the menu, the 
second takes it down; in between, the menu stays up. Default: FALSE 

MENU_STRINGS 

list of char * 

Create multiple string menu items. Set only. 

MENU_STRING_ITEM 

char *, value 

Create string menu item with value. Set only. 
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Table 19-13 Menu Attributes — Continued 



Attribute 

Value Type 

Description 

MENU_TITLE_ 

IMAGE 

Pixrect* 

Create image title item. Set only. 

MENU_TITLE_ 

ITEM 

char * 

Create string title item. Set only. 

MENU_TYPE 


enum 

Get only; returns MENU_MENU. 

MENU_VALID_ 

_RESULT 

boolean 

Tells whether a zero return value represents a legitimate value. 



Revision A, of May 9, 1988 










Chapter 19 — SunView Interface Summary (Menu Item Attributes) 339 


Table 19-14 Menu Item Attributes 




Attribute 

Value Type 

Description 

MENU_ACTION_IMAGEt 

Pixrect *, action proc 

Modifies appropriate fields in item. Set only. 

MENO_ACTION_ITEMf 

char *, action proc 

Modifies appropriate fields in item. Set only. 

MENU_ACTION_PROC 

(procedure) 

Client’s function called after item has been selected: 
caddr_t action_proc(menu, menu_item) 

Menu menu 

Menu_item menu_itern 

MENO_APPEND_ITEMf 

Menujtem 

Append item to end of menu. Set only. 

MENU_BOXEDf 

boolean 

If TRUE, a single-pixel box will be drawn around the item. 

MENU_CENTERf 

boolean 

If TRUE, the menu item will be centered on its row in the menu. 
Only meaningful for menu strings. 

MENU_CLIENT_DATAf 

caddr_t 

For use by the client. 

MENU_FEEDBACK 

boolean 

If FALSE, item is never inverted and is not selectable. 

MENU_FONTf 

Pixfont * 

Item’s font. 

MENO_GEN_PROCf 

(procedure) 

Client’s procedure called to generate the item. 

MENU_GEN_PROC_IMAGE 

Pixrect *, (procedure) 

Modifies appropriate fields in item. Set only. 

MENU_GEN_PROC_ITEM 

char *, (procedure) 

Modifies appropriate fields in item. Set only. 

MENU_GEN_PULLRIGHT 

generate proc 

Generate proc for the item’s pullright. 

MENU_GEN_PULLRIGHT_IMAGEf 

Pixrect *, (procedure) 

Modifies appropriate fields in item. Set only. 

MENU_GEN_PULLRIGHT_ITEMf 

char *, gen proc 

Modifies appropriate fields in item. Set only. 

MENU_IMAGE 

Pixrect * 

Item’s image. 

MENU_IMAGE_ITEMf 

char *, action proc 

Modifies appropriate fields in item. Set only. 

MENU_INACTIVE 

boolean 

If TRUE, item is grayed out and not selectable. 


t Many of the attributes in this table appeared in the previous table. Menus and menu items have many attributes in common. Attributes marked with 
“f” are also valid for menus, although the effect of the attribute may differ. 
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Table 19-14 Menu Item Attributes — Continued 


Attribute 

Value Type 

Description 

MENU_INVERT 

boolean 

If TRUE, item’s display is inverted. 

MENU_LEFT_MARGINf 

int 

Margin in addition of MENU_MARGIN on left between 
menu’s border and text. 

MENU_MARGINf 

int 

Margin in pixels around the item. 

MENU_PARENTf 

Menu 

The menu containing the item. 

MENU_PULLRIGHT 

Menu 

Item’s pullright menu. 

MENU_P ULLRIGHT_IMAGEf 

Pixrect *, Menu 

Modifies appropriate fields in item. Set only. 

MENU_P ULLRIGHT_ITEMt 

char *, Menu 

Modifies appropriate fields in item. Set only. 

MENO_RELEASE 

(no value) 

The item will be automatically destroyed when its parent 
menu is destroyed (default for items created inline). 

MENU_RELE ASE_I MAGE 

(no value) 

The string or pixrect associated with the item will be 
freed when the item is destroyed. 

MENU_RIGHT_MARGINf 

int 

Margin in addition of MENU_MARGIN on right between 
menu’s border and text 

MENG_SELECTEDt 

boolean 

If TRUE, the item is currently selected. 

MENU_STRINGf 

char * 

Item’s string. 

MENU_STRING_ITEMf 

char *, value 

Modifies appropriate fields in item. Set only. 

MENU_TYPEf 

enum 

Get only, returns MENU_ITEM. 

MENU_VALOE 

caddr_t 

Item's value. 
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Table 19-15 Menu Functions 


Definition 

Description 

Menu 

menu_create(attributes) 

<attribuXe-list> a tt r ibut e s; 

Creates and returns the opaque handle for a walking menu. 

Menu_item 

menu_create_item(attributes) 

<attribute-list> attributes; 

Creates and returns the opaque handle for a single item 
within a walking menu. 

void 

menu__dest roy (menu__ob j ect) 

<Menu or Menu_item> menu ob j ect; 

Destroys a menu or menu item. 

void 

menu_destroy_with_proc (menu__object, destroy proc) 
<Menu or Menu_item> menu_ob j ect; 
void (*destroy_j?roc)(); 

The function supplied as dest roy_proc is called before 
the menu or menu item is destroyed. Arguments: 
de st roy_j?roc (menu_ob j ect, type) 

<Menu or Menu_item> menu object; 
Menu_attribute type; 
type is MENU_MENU for menus, MENU_ITEM for items. 

Menu_item 

menu__f ind (menu, attributes) 

Menu menu; 

<attribute-list> attributes; 

Returns the first menu item in menu meeting the criteria 
specified in attributes. 

caddr_t 

menu_get (menu_ob ject, attribute[, optional arg]) 

<Menu or Menu_item> menu object; 

Menu_attribute attributes; 
caddr_t optional_arg; 

Retrieves the value for an attribute of a menu or menu item. 

int 

menu_set(menu_object, attributes) 

<M enu or Menu_item> menu_ob j ec t; 

<attribute-list> a tt ribu t e s; 

Sets the value of one or more attributes for a menu or menu. 

item, attributes is a null-terminated attribute list 

caddr t 

menu^show(menu, window, event, 0) 

Menu menu; 

Window window; 

Event *event; 

Displays the menu, gets a selection from the user, and, by 
default, returns the value of the item the user has selected. 

window is the handle of the window over which the menu 
is displayed; event is the event which causes the menu to 
come up. The final argument is currently ignored. 
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Table 19-15 Menu Functions— 

Continued 

Definition 

Description 

caddr_t menu_show_using__fd (menu, fd, event) 
Menu menu; 

int fd; 

Event *event; 

Provided for compatibility with SunWindows 2.0. Allows 
you to display a menu within a window using the windowfd. 

caddr__t 

menu_return_item (menu, menu_item) 

Menu menu; 

Menu_item menu_item; 

Predefined notify proc which, if given as the value for 

MENU NOTIFY PROC, causes menu_show () to return 
the handle of the selected item, rather than its value. 

caddr__t 

menu_return_value (menu, menu__item) 

Menu menu; 

Menu item menu item; 

Default notify proc for menus. Causes menu_show () 
to return the value of the selected item. 
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Table 19-16 Notifier Functions 



Definition 

-I 

Description 

Notify__value 



Predefined function you can register with the Notifier via the 

notify_default_wait3 (client, pid. 

status, rusage) 

notify_set_wait3_func () call. Causes the required 

Notify_client 

client; 


housekeeping to be performed on the process identified by pid 

int 

pid; 


when it dies. See the wait(2) man page for details of the 

union wait 

*status; 


wait and rusage structures. 

struct rusage 

*rusage; 






Provided to allow programs which are not notification-based to 

Notify_error 



run in the SunView environment. Called regularly from within 

notify_dispatch() 



the application’s main loop to allow the Notifier to go once 
around its internal loop and dispatch any pending events. 

Notify_error 



Called once, before the application’s main loop. Enables 

not ify__do_dis patch () 


“implicit dispatching,” in which the Notifier dispatches 




events from within calls to read(2) or select(2). 

Notify_error 




notify_interpose_destroy_func(client, destroy func) 

Interposes destroy_f unc () in front of 

Notify_client 

client; 


client’s destroy event handler. 

Notify__func 

destroy_func; 



Notify__error 




notify_interpose__event_func (client 

t 



event_ 

func, type) 

Interposes event_func () in front of 

Notify_client 

client; 


client’s event handler. 

Notify_func 

event_func; 



Notify_event_type type; 



Notify_error 




notify_itimer_value(client, which. 

value) 

Returns the current state of an interval timer for client in the 

Notify_client 

client; 


structure pointed to by value. The which parameter 

int 

which; 


is either ITIMER_REAL or ITIMER_VIRTUAL. 

struct itimerval *value; 



Notify_value 




notify_next_destroy_func (client, status) 

Calls the next destroy event handler for client. 

Notify_client 

client; 


status returns DESTROY_PROCESS DEATH, 

Destroy_status 

status; 


DESTROY_CHECKING, or DESTROY_CLEANUP. 
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Table 19-16 Notifier Functions — Continued 


Definition 

Description 

Notify_value 

notify next_event_func(client, event, arg, type) 
Notify_client client; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

Calls the next event handler for client. 

Notify__error 
notify_no_dispatch () 

Prevents the Notifier from dispatching events from within the 
call to read(2) or select(2). 

void 

notify_perror(s) 
char *s; 

Analogous to the UNIX perror(3) system call, 
s is printed to stderr, followed by a terse description of 
notify_errno (). 

Notify_func 

notify set_destroy_func (client, destroy_func) 
Notify_client client; 

Not i f y_func de st roy_func; 

Registers destroy_func () with the Notifier. 
destroy func () will be called when a 
destroy event is posted to client or when the process 
receives a SIGTERM signal. 

Notify_func 

Registers the exception handler exception_func () 


notify_set_exception_func (client, exception_func, fd) with the Notifier. The only known devices that generate 


Notify__client client; 

Notify_func exception_func; 

int fd; 

exceptions at this time are stream-based socket 
connections when an out-of-band byte is available. 

Notify_func 

notify set_input_func(client, input_func, fd) 

Notify client client; 

Notify_func input_func; 

int fd; 

Registers input__f unc () with the Notifier. 
input func () will be called whenever 
there is input pending on f d. 

Notify_func 



notify_set_itimer_func (client, itimer_func, which. Registers the timeout event handler itimer_func () 


value, ovalue) 

Notify_client client; 

Notify__func itimer_func; 

int which; 

struct itimerval *value, *ovalue; 

with the Notifier. The semantics of which, value 
and ovalue parallel the arguments to setitimer 
(see the getitimer manual page), 
which is either ITIMER_REAL or ITIMER_VIRTUAL. 
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Table 19-16 Notifier Functions — Continued 


Definition 

Description 

Notify_func 

notify_set__signal__func (client, signal_func, 

signal, when) 

Notify_client client; 

Notify__func signal_func; 

int signal; 

Notify_signal_mode when; 

Registers the signal event handler signal_func () with 
the Notifier. signal_f unc () will be called whenever 
signal is caught by the Notifier. when can be either 
NOTIFY_SYNC or NOTIFY_ASYNC. 

Calling not if y_set_signal_func () with a NULL in the 
place of the signal_func () turns off checking for that 
signal for that client. 

Notify__error 
notify_start() 

Begins dispatching of events by the Notifier. 

Notify_error 
notify_stop () 

Terminates dispatching of events by the Notifier. 

Notify_func 



not if y_set_output_func (client, output_func, fd) Registers out put_func () with the Notifier. 


Notify_client client; 

Notify_func output_func; 

int fd; 

output_f unc () will be called whenever 
output has been completed on f d. 

Notify_func 

notify_set_wait3_func(client, wait3 func, pid) 
Notify_client client; 

Notify_func wait3_func; 

int pid; 

Registers the function wait3__func () with the Notifier. 

The registered function will be called after the child 
process identified by pid dies. To do the minimum 
processing, register the predefined function 
notify_default_wait3 (). 

Notify error 

notify_veto_destroy(client) 

Notify_client client; 

Called from within a destroy event handler when status 
is DESTROY_CHECKING and the application does not 
want to be destroyed. 
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Table 19-17 Panel Attributes 


Attribute 

Value Type 

Description 

PANEL_ACCEPT_KEYSTROKE 

boolean 

If TRUE, keystroke events are passed 

to the panel’s PANEL_BACKGROUND_PROC. Default: FALSE. 

PANEL_BACKGROUND_PROC 

(procedure) 

Event handling procedure called when an 
event falls on the background of the panel. Form: 
background_proc(panel, event) 

Panel panel 

Event *event 

PANE L_BLINK_CARET 

boolean 

If TRUE, the caret blinks. Default: setting of Blink caret in the Text 
category of defaultsedit. 

PANEL_CARET_ITEM 

Panel_item 

Text item which currently has the caret. 

Default: first text item. 

PANEL_EVENT_PROC 

(procedure) 

Event handling procedure for panel items. 

Sets the default for subsequent items created in panel. Form: 
event_proc(item, event) 

Panel_item item 

Event *event 

PANE L_FIRST_ITEM 

Panel_item 

First item in the panel. Get only. 

P ANEL_I TEM_X_GAP 

int 

Number of x-pixels between items. Default: 10. 

PANEL_ITEM_Y_GAP 

int 

Number of y-pixels between items. Default: 5. 

PANEL_LABEL_BOLD 

boolean 

If TRUE, item’s label is rendered in bold. 

Sets the default for subsequent items created in panel. Default: FALSE. 

PANEL_LAYOUT 

Panel_setting 

Layout of item’s value relative to the label. 

PANEL_HORI ZONTAL (default) or PANEL_VERTICAL. 

PANEL_SHOW_MENU 

boolean 

If TRUE, the menu for the item is enabled. 

Sets the default for subsequent items created in panel. 
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Table 19-18 Generic Panel Item Attributes 


Attribute 

Value Type 

Description 

PANEL_ACCEPT_KEYSTROKE 

boolean 

If TRUE, keystroke events are passed to the item’s EVENT PROC. 

PANEL_CLIENT_DATA 

caddr_t 

For application’s use. 

PANEL_EVENT_PROC 

(procedure) 

Event handling procedure for the item. 

PANEL_ITEM_RECT 

Rect * 

Enclosing rectangle for the item. Get only. 

PANEL_ITEM_X 

int 

Left edge of item rectangle. If unspecified and label or value positions are 
fixed, then set to min of PANEL_LABEL_X and PANEL_VALUE X. 
Default: after lowest, rightmost item 

PANEL_ITEM_Y 

int 

top edge of item rectangle. If unspecified and label or value positions are 
fixed, then set to min of PANEL_LABEL_Y and PANEL VALUE Y. 
Default: previous item’s PANEL ITEM Y. 

PANEL__LABEL_X 

int 

Left edge of label. If unspecified and value position is fixed, then set to 
left of PANEL_VALUE_X for horizontal layout, or at PANEL_VALUE X 
for vertical layout. Default: PANEL ITEM X. 

PANEL_LABEL_Y 

int 

Top edge of label. If unspecified and value position is fixed, then set to 
PANEL_VALUE_Y for horizontal layout, or above PANEL VALUE Y 
for vertical layout. Default: PANEL_ITEM Y. 

PANEL_LABEL_BOLD 

boolean 

If TRUE, item’s label is rendered in bold. Default: FALSE. 

PANEL_LABEL_FONT 

Pixfont * 

Font for PANEL_LABEL_STRING. Default: WIN_FONT. 

PANEL__LABEL_IMAGE 

Pixrect* 

Image for item’s label. 

PANEL_LABEL_STRING 

char * 

String for item’s label. 

P ANEL_LAY OUT 

Panel_setting 

Layout of item’s value relative to the label. PANEL HORIZONTAL 
(default) or PANEL_VERT I CAL. 

PANE L_MENU_CHOICE_FONTS 

list of Pixfont * 

Font for each menu choice string. Create, set. Default: WIN FONT. 

PANE L_MEN U__CHO I CE_I MAGE S 

list of Pixrect * 

Image for each menu choice. Create, set. Default: 

PANEL_CHOICE_IMAGES for choice items, PANEL LABEL IMAGE 
for button items, NULL for other items. 

PANEL_MENU_CHOICE_STRINGS 

list of char * 

String for each menu choice. Create, set. Default: 
PANEL_CHOICE_STRINGS for choice items, NULL for other items. 

PANE L_MENU_CHOICE_VALUES 

list of caddr_t 

The values returned from the item’s menu. Create, set 
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Table 19-18 Generic Panel Item Attributes — Continued 


Attribute 

Value Type 

Description 

PANEL_MENU_TITLE_FONT 

Pixfont * 

Font for PANEL_MENU_TITLE_STRING. 

PANEL_MENUJTITLE_IMAGE 

Pixrect * 

Image for the menu title. 

PANEL_MENU_TITLE_STRING 

char * 

String for the menu title. 

PANEL_NEXT_ITEM 

Panel_item 

Next item in the panel. Get only. 

PANEL_NOTIFY_PROC 

(procedure) 

Function to call when item is selected. Form for button and text items: 
notify_j?roc (item, event) 

Panel_item item 

Event *event 

Choice and slider items have an additional parameter for the current value: 
notify__proc (item, value, event) 

Panel_item item 
int value 

Event *event 

For toggle items, the value parameter is of type unsigned int. 

The type for a text item notify_j?roc is Panel__setting. 

PANEL_PAINT 

Panel_setting 

Item’s painting behavior for panel__set () calls. One of: 

PANEL_NONE, PANEL_CLEAR, or PANEL_NO_CLEAR 

PANEL_PARENT_PANEL 

Panel 

The panel which contains the item. 

PANEL_SHOW_ITEM 

boolean 

Whether or not to show the item. Default: TRUE. 

PANEL_SHOW_MENU 

boolean 

If TRUE, the menu for the item is enabled. 

PANEL_VALOE_X 

int 

Left edge of value. If unspecified and label position is fixed, 
then set to right of PANEL__LABEL_X for horizontal layout, or 
at PANEL LABEL X for vertical layout. Default: after the label. 

PANEL_VALOE_Y 

int 

Top edge of value. If unspecified and label position is fixed, then set 
to PANEL LABEL Y for horizontal layout, or below 

PANEL LABEL Y for vertical layout. Default: PANEL_LABEL_Y. 
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Table 19-19 Choice and Toggle Item Attributes 



.... 

n - j 

Attribute 

Value Type 

Description 

PANEL_CHOICE_FONTS 

list of Pixfont * 

Font to use for each choice string. Create, set. 

PANEL_CHOICE_IMAGE 

int, pixrect * 

Image for choice specified by the first argument. 

PANEL_CHOICE_IMAGES 

list of Pixrect * 

Image for each choice. Create, set. 

PANEL_CHOICE_STRING 

int, char * 

String for choice specified by first argument. 

PANEL_CHOICE_STRINGS 

list of char * 

String for each choice. Note that you must specify at 
least one choice — the least you can specify is a single 
null string (PANEL_CHOICE_STRINGS, 0). 

Create, set. 

PANEL_CHOICE_X 

int, int 

Second argument is left edge of choice specified by first 
argument. 

PANEL_CHOICE_XS 

list of int 

Left edge of each choice. Create, set. 

PANEL_CHOICE_Y 

int, int 

Second argument is top edge of choice specified by first 
argument. 

PANEL_CHOICE_YS 

list of int 

Top edge of each choice. Create, set. 

PANEL_CHOICES_BOLD 

boolean 

If TRUE, choices strings are in bold. Default: FALSE. 

PANEL_DISPLAY_LEVEL 

Panel_setting 

How many choices to display. One of PANEL_NONE, 
PANEL_CURRENT, or PANEL_ALL. Default: 

PANEL_ALL. 

PANEL_FEEDBACK 

Panel_setting 

Feedback to give when a choice is selected. One of 
PANEL_NONE, PANEL_MARKED, 

PANEL_INVERTED. If PANEL__DISPLAY_LEVEL is 
PANEL CURRENT, default is PANEL_NONE, otherwise 
PANEL_MARKED. 

PANEL_LAYOUT 

Panel_setting 

Layout of the choices: PANEL_HORIZONTAL (default) 
or PANEL_VERT I CAL. 

PANEL_MARK_IMAGE 

int, Pixrect * 

Image to mark choice specified by the first argument 
when it is selected. Default is push-button image: 
<images/panel__choice_on. pr>. 
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Table 19-19 

Choice and Toggle Item Attributes — Continued 

Attribute 

Value Type 

Description 

P ANEL_MARK_I MAGE S 

list of Pixrect * 

Image to mark each choice with when selected. Create, 
set only. Default is push-button image: 
<images/panel_choice_on.pr>. 

P ANE L_MARK_X 

int, int 

Second argument is left edge of choice mark specified by 
first argument. 

PANEL_MARK_XS 

list of int 

Left edge of each choice mark. Create, set. 

PANEL_MARK_Y 

int, int 

Second argument is top edge of choice mark specified by 
first argument. 

PANEL_MARK_YS 

list of int 

Top edge of each choice mark. Create, set. 

PANEL_MENU_MARK_IMAGE 

Pixrect * 

Image to mark each menu choice with when selected. 

P ANEL_MENU_NOMARK_I MAGE 

Pixrect * 

Image to mark each menu choice with when not selected. 

PANEL_NOMARK_IMAGE 

IP 

int, Pixrect * 

Image to mark choice specified by the first argument 
when it is not selected. Default is push-button image: 
<images/panel_choice off.pr>. 

PANEL_NOMARK_IMAGES 

list of Pixrect * 

Image to mark each choice with when not selected. 

Create, set. Default is push-button image: 
<images/panel_choice__of f. pr>. 

PANEL_SHOW_MENU_MARK 

boolean 

Show or don’t show the menu mark for each selected 
choice. Default: TRUE. 

PANEL_TOGGLE__VALUE 

int, int 

Value of a particular toggle choice. Second argument is 
value of choice specified by first argument 

PANEL_VALUE 

int or unsigned 

If item is a choice, value is ordinal position (from 0) of 
current choice. If item is a toggle, value is a bitmask 
indicating currently selected choices (e.g., bit 5 is 1 if 

5th choice selected). 
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Table 19-20 

Slider Item Attributes 

Attribute 

Value Type 

Description 

PANEL_MIN_VALUE 

int 

Minimum value of slider. Default: 0. 

PANE L_MAX_VALUE 

int 

Maximum value of the slider. Default: 100. 

PANEL_NOTIFY_LEVEL 

Panel_setting 

When to call the notify function: PANEL_DONE notifies when the 
select button is released, P ANEL_ALL notifies continuously as the 
select button is dragged. Default: PANEL_DONE. 

PANE L_SH OW_RAN GE 

boolean 

Show or don’t show the min and max slider values. Default: TRUE. 

PANE L_SHOW_VALUE 

boolean 

Show or don’t show integer value of slider. Default: TRUE. 

PANEL_SLIDER__WI DTH 

int 

Width of the slider bar in pixels. Default: 100. 

PANEL_VALUE 

int 

Initial or new value for the item, in the range 

P ANE L_M I N_VAL UE to PANE L_MAX_VALUE. Default: 
PANEL_MIN_VALUE. 

PANEL_VALUE_FONT 

Pixfont * 

Font to use when displaying the value. 
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Table 19-21 

Text Item Attributes 


Attribute 

Value Type 

Description 

P ANE L_MAS K_CHAR 

char 

Character used to mask type-in characters. Use the space character 
for no character echo (caret does not advance). Use the null char¬ 
acter to disable masking. 

PANEL_NOTIFY_LEVEL 

Panel_setting 

When to call the notify function. One of PANEL_NONE, 

PANEL_NON_PRINTABLE, PANEL_SPECIFIED, or 

PANEL_ALL. Default: PANEL_SPECIFIED (see Text 
Notification). 

PANEL_NOTIFY_STRING 

char * 

String of characters which trigger notification when typed. 

Applies only when PANEL_NOTIFY_LEVEL is 
PANEL__SPECIFIED. Default: \n\r\t (newline, carriage return 
and tab). 

PANEL_VALUE_STORED__LENGTH 

int 

Max number of characters to store in the value string. Default: 80. 

P ANEL_VALUE_DI SPLAY__LENGTH 

int 

Max number of characters to display in the panel. Default: 80. 

PANEL_VALUE 

char * 

Initial or new string value for the item. 

PANEL VALUE F ONT 

Pixfont * 

Font to use for the value string. 
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Table 19-22 Panel Functions and Macros 


m 
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■ 
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Definition 

Description 

panel_accept_key(object, event) 

<Panel or Panel_item> object ; 

Event *event; 

Action function which tells a text item to accept a keyboard event. 
Currently ignored by non-text panel items. 

panel_accept_menu(object, event) 

<Panel or Panel_item> object; 

Event *event; 

Action function which tells an item to display its menu and process 
the user’s selection. 

panel_accept_preview(object, event) 

<Panel or Panel_item> object ; 

Event *event; 

Action function which tells an item to do what it is supposed to do 
when it is selected. This may include completing feedback 
initiated by panel_begin_preview (). 

Panel__item 

panel_advance_caret(panel) 

Panel panel; 

Advance the caret to the next text item. If on the last 

text item, rotate back to the first. Returns the new 
caret item, or NULL if there are no text items. 

Panel_item 

panel_backup_caret(panel) 

Panel panel; 

Backup the caret to the previous text item. If on the 
first text item, rotate back to the first. Returns the 
new caret item, or NULL if there are no text items. 

panel_begin_preview(object, event) 

<Panel or Panel_item> object ; 

Event *event; 

Action function which tells an item to begin any feedback which 
indicates tentative selection. 

Pixrect * 



panel_button_image (panel, string, width, font) Creates a standard, button-like image from a string. The string is 


Panel panel; 
char *string; 

int width; 

Pixfont *font; 

rendered in font, centered within a double-pixel border width 
characters wide. If width is too narrow for the string, the border 
will be expanded to contain the entire string. If font is 0, 
panel’s font is used. 

panel__cancel_preview (object, event) 

<Panel or Panel_item> object ; 

Event *event; 

Action function which tells an item to cancel the feedback initiated 
by panel_begin_jpreview (). 

Panel_item 

Creates and returns the opaque handle to a panel item. item__type 


panel_create_item(panel, item_type, attributes) is one of: PANEL_MESSAGE, PANEL_BUTTON, PANEL_CHOICE, 


Panel panel; 

<itemtype> item_type; 

<attribute-list> attributes; 

PANEL_CYCLE, PANEL_TOGGLE, PANELJTEXT or 

PANEL_SLIDER. attributes is a null-terminated attribute list. 
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Table 19-22 Panel Functions and Macros — Continued 


Definition 

Description 

panel default__handle_event(object, event) 
<Panel or Panel_item> object ; 

Event *event; 

The default event proc for panel items (PANEL_EVENT_PROC) 
and for the panel’s background (PANEL_BACKGROUND_PROC). 
Implements the standard event-to-action mapping for the item types. 

panel destroy_item(item) 

Panel__item item; 

Destroys item. 

panel_each_item (panel, item) 

Panel panel; 

Panel_item item; 

Macro to iterate over each item in a panel. The corresponding macro 
panel_end_each closes the loop opened by 
panel_each_item(). 

Event * 

panel_event (panel, event) 

Panel panel; 

Event *event; 

Translates the coordinates of event from the space of the panel 
subwindow to the space of the logical panel 
(which may be larger and scrollable). 

caddr__t 

panel_get(item, attribute[, optional_arg]) 
Panel_item item; 

Panel_attribute attribute; 

Panel_attribute optional_arg; 

Retrieve the value of an attribute for item. optional__arg is 
used for a few attributes which require additional information, 
such as PANEL__CHOI CE_IMAGE, PANEL_CHOICE_STRING, 

P ANEL_CHO I CE_X, PANEL_CHOICE_Y, 

PANEL_MARK_X, PANEL_MARK__Y, PANEL_TOGGLE_VALUE. 

caddr_t 

panel get_value (item) 

Panel__item item; 

A macro, defined as: 

panel_get (item, PANEL_VALUE) 

panel_paint(panel_object, paint_behavior) 
<Panel_item or Panel> panel_ob j ect; 
Panel_setting paint_behavior; 

Paints an item or an entire panel. paint_behavior can be either 
PANEL_CLEAR or PANEL_NO_CLEAR. PANEL_CLEAR causes 
the area occupied by the panel or item to be cleared prior to painting. 

panel_set(item, attributes) 

Panel_item item; 

<attribute-list> att ribut e s; 

Sets the value of one or more panel attributes, 
attributes is a null-terminated attribute list. 

panel set_value(item, value) 

Panel_item item; 
caddr__t value; 

A macro, defined as: 

panel__set (item, PANEL_VALUE, value, 0) 

Panel_setting 

panel_text_notify(item, event) 

Panel item item 

Event *event 

Default notify procedure for panel text items. Causes caret 
to advance on CR or tab, caret to backup on shift-CR or shift-tab, 
printable characters to be inserted into item's value, 
and all other characters to be discarded. 
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Table 19-22 

Panel Functions and Macros — Continued 

Definition 


Description 

panel_update_preview(object, 
<Panel or Panel_item> object ; 
Event *event; 

event) 

Action function which tells the item to update its previewing 
feedback (e.g. redraw the slider bar for a slider item). 

panel_update_scrolling size(panel) 

Panel panel; 

Updates the scrollbar’s notion of the panel’s size, 
so the scrollbar’s bubble will be the correct size. 

Event * 

panel__window__event (panel, event) 

Panel panel; 

Event *event; 

Translates the coordinates of event to the space of the panel 
subwindow from the space of the logical panel 
(which may be larger and scrollable). 
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Table 19-23 Pixwin Drawing Functions and Macros 


Definition 

Description 

pw_batch(pw, n) 

Pixwin *pw; 

Pw batch_type n; 

Tells the batching mechanism to refresh the screen every 
n display operations. 

pw_batch_off(pw) 

Pixwin *pw; 

A macro to turn batching off in pw. 

pw_bat ch_on(pw) 

Pixwin *pw; 

A macro to turn batching on in pw. 

pw batchrop(pw, dx, dy, op, items, n) 

Pixwin *pw; 

int dx, dy, op, n; 

struct pr_prpos items[]; 

See the Pixrect Reference Manual for a full explanation 
of this function. 

pw char(pw, x, y, op, font, c) 

Pixwin *pw; 

int x, y, op; 

Pixfont *font; 

char c; 

Writes character c into pw using the rasterop op. 

The left edge and baseline of c will be written at 
location (x, y). 

pw_close(pw) 

Pixwin *pw; 

Frees any dynamic storage associated with pw, 
including its retained memory pixrect, if any. 

pw_copy(dpw, dx, dy, dw, dh, 
op, spw, sx, sy) 

Pixwin *dpw, *spw; 

int op, dx, dy, dw, dh, sx, sy; 

Copies pixels from spw to dpw. Currently spw and 
dpw must be the same. This routine will cause problems if 
spw is obscured. 

int 

pw_get(pw, x, y) 

Pixwin *pw; 

int x, y; 

Returns the value of the pixel at (x, y) in pw. 

int 

pw_get_region_rect (pw, r) 

Pixwin *pw; 

Rect *r; 

Retrieves the rectangle occupied by the region pw 
into the rect pointed to by r. 
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Table 19-23 Pixwin Drawing Functions and Macros — Continued 



Definition 

Description 

pw__line(pw, xO, yO, xl, yl, brush, tex, op) 
Pixwin *pw; 

int xO, yO, xl, yl, op; 

struct pr_brush *brush; 

struct pr_texture *tex; 

Draws a solid or textured line between two points with a 
“brush” of a specified width. 

pw lock(pw, r) 

Pixwin *pw; 

Rect *r; 


Acquires a lock for the user process making the call, 
r is the rectangle in pw’s coordinate system 
that bounds the area to be affected. 

pw_jpf sysclose () 


Closes the system font opened with pw_pf sysopen (). 

Pixfont * 

pw_jpf sysopen () 


Opens the system font. 


pw_j?olygon_2(pw, dx, dy f nbds, npts. 


vlist, op f spr, sx, sy) 

Pixwin *pw; 

int dx, dy, nbds, op, sx, sy; Draws a polygon in pw. 

int npts[]; 

struct pr_pos *vlist; 

Pixrect *spr; 


pw_polyline(pw, dx, dy, npts, 

ptlist, mvlist, brush, tex, op) 


Pixwin 


*pw; 


int 


dx, dy, npts, op; 

Draws multiple lines of a specified width and texture in 

struct 

pr_pos 

*ptlist; 

pw. 

u__char 


*mvlist; 


struct 

pr_brush 

*brush; 


struct 

pr_texture 

*tex; 



pw_polypoint(pw, dx, dy, npts, ptlist, op) 

Pixwin *pw; _ _ ..... 

Draws an array of npts points m the pixwm pw 

int dx, dy, npts, op; 

struct pr_pos *ptlist; 


pw_put(pw, x, y, value) 

Pixwin *pw; Draws a pixel of value at (x, y) in pw. 

int x, y, value; 
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Table 19-23 Pixwin Drawing Functions and Macros — Continued 


Definition 

Description 

pw__read(pr, dx, dy, dw, dh, op, pw, sx, sy) 

Pixwin *pw; 

int op, dx, dy, dw, dh, sx, sy; 

Pixrect *pr; 

Reads pixels from the pixwin pw starting at offset (sx, 
sy), using rasterop op. The pixels are stored in the rec¬ 
tangle (dx, dy, dw, dh) in the pixrect pointed to by pr. 

Pixwin * 

pw_region(pw, x, y, width, height) 

Pixwin *pw; 

int x, y, w, h; 

Creates a new pixwin refering to an area within the existing 
pixwin pw. The origin of the new region is given by (x, 
y), the dimensions by width and height. 

pw_replrop(pw, dx, dy, dw, dh, 
op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 

Replicates a pattern from a pixrect into a pixwin. 

pw_reset(pw) 

Pixwin *pw; 

Macro which sets pw’s lock count to 0 and releases its lock. 

pw_rop(pw, dx, dy, dw, dh, 
op, sp, sx, sy) 

Pixwin *pw; 

Pixrect *sp; 

int dx, dy, dw, dh, op, sx, sy; 

Performs the rasterop op from the source pixrect 
sp to the destination pixwin pw. 

int 

pw_set_region_rect (pw, r, use_same_pr) 

Pixwin *pw; 

Rect *r; 

unsigned int use_same_j?r; 

The position and size of the region pw are set to the rect 
*r. 

If use_same_pr is 0 a new retained pixrect is allocated 
for the region. 

pw_show(pw) 

Pixwin *pw; 

Macro to refresh the screen while batching, without affect¬ 
ing the batching mode. 

pw__stencil (dpw, dx, dy, dw, dh, op, 

stpr, stx, sty, spr, sx, sy) 

Pixwin *dpw; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 

Pixrect *stpr, *spr; 

Like pw_write (), except that the source pixrect spr is 
written through the stencil pixrect stpr, which functions 
as a spatial write enable mask. The raster operation op is 
only applied to destination pixels where the stpr is non¬ 
zero; other destination pixels remain unchanged. 

pw_text(pw, x, y, op, font, s) 

Pixwin *pw; 

int x, y, op; 

Pixfont *font; 

char *s; 

Writes the string s into pw using the rasterop op. 

The left edge and baseline of the first character in s will 
appear at coordinates (x, y). 
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Table 19-23 Pixwin Drawing Functions and Macros — Continued 


Definition 

Description 

pw_traprop(pw, dx, dy f t, op, pr f sx, sy) 

Pixwin *pw; 

struct pr_trap t; 

Pixrect *pr; 

int dx, dy, op, sx, sy; 

Like pw_rop (), but operating on a trapezon rather than a 
rectangle. 

pw_ttext(pw, x, y, op, font, s) 

Pixwin *pw; 
int x, y, op; 

Pixfont *font; 

char *s; 

Like pw_text () except that it writes “transparent” text, 
i.e. it writes the shape of the letters without disturbing the 
background behind the letters. 

pw_unlock(pw) 

Pixwin *pw; 

Decrements the lock count for pw. If the lock count goes 
to 0, the lock is released. 

pw_vector(pw, xO, yO, xl, yl, op, value) 

Pixwin *pw; 

int op, xO, yO, xl, yl, value; 

Draws a vector of pixel value from (xO, yO) to (xl, 
yl)in pw using rasterop op. 

pw_write(pw, dx, dy, dw, dh, 
op, pr, sx, sy) 

Pixwin *pw; 

int dx, dy, dw, dh, op, sx, sy; 

Pixrect *pr; 

Writes pixels to pw in the rectangle defined by dx, dy, 
dw, dh, using rasterop op. Pixels to write are taken from 
the rectangle with its origin at sx, sy in the source pix¬ 
rect pointed to by pr. 

Note: this is an alternative form of pw_rop. 

pw_writebackground(pw, dx, dy, dw, dh, op) 

Pixwin *pw; 

int dx, dy, dw, dh, op; 

Writes pixels with value zero into pw using the rasterop op. 
xd, yd, width and height specify the rectangle in 
pw which is affected. 
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Table 19-24 Pixwin Color Manipulation Functions 




mm. 


Definition 


Description 

pw_blackonwhite(pw, min, max) 

Pixwin *pw; 

int min, max; 


Sets the foreground to black, the background to white, for pixwin 
pw. min and max should be the first and last entries, respectively, 
in pw’s colormap segment. 

pw cyclecolormap(pw, cycles, index, 
Pixwin *pw; 

int cycles, index, count; 

count) 

Rotates the portion of pw’s colormap segment starting at index 
for count entries, rotating those entries among themselves 
cycles times. 

pw_dbl_access (pw) 

Pixwin *pw; 


Resets the window’s data structure so that the first frame will be ren¬ 
dered to the background. 

pw dbl_flip(pw) 

Pixwin *pw; 


Allows you to flip the display. 

pw_dbl_get(pw, attribute) 

Pixwin *pw; 

Pw__dbl_at tribute attribute; 


Retrieves the value of the specified attribute. 

pw_dbl_release () 

Pixwin *pw; 


Signifies the end of double-buffering by the window associated with 
the pixwin. 

pw_dbl_set(pw, attributes) 

Pixwin *pw; 

<attribute- list> attributes; 


Sets the pixwin hardware double-buffering attributes in attri¬ 
butes. 

pw_getattributes(pw, planes) 

Pixwin *pw; 
int *planes; 


Retrieves the value of pw’s access enable mask 
into the integer addressed by planes. 

pw_getcmsname(pw, cmsname) 

Pixwin *pw; 

char cmsname [CMS_NAMESIZE]; 


Copies the colormap segment name of pw into cmsname. 

pw_getcolormap(pw, index, count, 
red, green, blue) 
Pixwin *pw; 

int index, count; 

unsigned char red[], green[], 

blue[]; 

Retrieves the state of pw’s colormap. The count elements 
of the pixwin’s colormap segment starting at index 
(0 origin) are loaded into the first count values in the 
three arrays. 
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Table 19-24 Pixwin Color Manipulation Functions — Continued 


Definition 

Description 

pw_getdefauItems (ems, map) 
struct colormapseg *cms; 
struct cms_map *map; 

Copies the data in the default colormap segment into 

the data pointed to by ems and map. Before the call, the byte pointers 

in map should be initialized to arrays of size 256. 

pw__putattributes (pw, planes) 

Pixwin *pw; 
int *planes; 

Sets the access enable mask of pw. Only those bits of the pixel 
corresponding to a 1 in the same bit position of *planes will be 
affected by pixwin operations. 

pw_j?utcolormap (pw, index, count, 
red, green, blue) 

Pixwin *pw; 

int index, count; 

unsigned char red[], green[], blue[]; 

Sets the state of pw’s colormap. The count elements of the 
pixwin’s colormap segment starting at index (0 origin) are loaded 
from the first count values in the three arrays. 

pw_reversevideo(pw, min, max) 

Pixwin *pw; 

int min, max; 

Reverses the foreground and background colors of pw 
min and max should be the first and last entries, 
respectively, in the colormap segment. 

pw_setcmsname(pw, emsname) 

Pixwin *pw; 

char emsname [CMS_NAMESIZE]; 

emsname is the name that pw will call its window’s 

colormap segment. This call resets the colormap segment to NULL. 

pw_whiteonblack(pw, min, max) 

Pixwin *pw; 

int min, max; 

Sets the foreground to white, the background to black, for pw. 
min and max should be the first and last entries, respectively, in the 
colormap segment. 
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Table 19-25 

Scrollbar Attributes 



Attribute 

Value Type 

Description 

SCROLL_ABSOLUTE_CURSOR 

Cursor 

Cursor to display on middle button down. 

Default: Right triangle if vert., down triangle if horiz. 

SCROLL_ACTIVE_CURSOR 

Cursor 

Cursor to display when cursor is in bar rect. 

Default: Right arrow if vertical, down arrow if horiz. 

SCROLL_ADVANCED_MODE 

boolean 

Whether notify proc reports all nine motions. Default: FALSE. 

SCROLL_BACKWARD_CURSOR 

Cursor 

Cursor to display on right button down. 

Default: up arrow if vertical, left arrow if horiz. 

SCROLL_BAR_COLOR 

Scrollbar_setting 

Color of bar, SCROLL_GREY (default) or SCROLL_WHITE. 

SCROLL_BAR_DISP LAY_LEVEL 

Scrollbar_setting 

When bar is displayed. 

SCROLL_ALWAYS: always displayed 

SCROLL ACTIVE: only displayed when cursor is in bar rect 
SCROLL NEVER: never displayed 

Default: SCROLL_ALWAYS. 

SCROLL_BORDER 

boolean 

Whether the scrollbar has a border. 

SCROLL_BUBBLE_COLOR 

Scrollbar_setting 

Color of bubble, SCROLL_GREY (default) or SCROLL_BLACK. 

SCROLL_BUBBLE_DISPLAY_LEVEL 

Scrollbar_setting 

When bubble is displayed. 

SCROLL_ALWAYS: always displayed 

SCROLL ACTIVE: only displayed when cursor is in bar rect 
SCROLL_NEVER: never displayed 

Default: SCROLL_ALWAYS. 

SCROLL_BUBBLE_MARGIN 

int 

Margin on each side of bubble in bar. Default: 0. 

SCROLL_DIRECTION 

Scrollbar_setting 

Orientation of bar, 

SCROLL_VERT ICAL (default) or SCROLL_HORI ZONTAL. 

SCROLL_END_POINT_AREA 

int 

The distance, in pixels, from the end of the scrollbar 
that forces a scroll to the beginning (or end) of the file. 

Default: 6. 

SCROLL_FORWARD_CURSOR 

Cursor 

Cursor to display on left button down. 

Default: down arrow if vertical, right arrow if horiz. 

SCROLL_GAP 

int 

Gap between lines. Default: current value of SCROLL_MARGIN. 
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Table 19-25 Scrollbar Attributes — Continued 


Attribute 

Value Type 

Description 

SCROLL_HEIGHT 

int 

r_height for scrollbar’s rect. 

SCROLLJLAST_VIEW_START 

int 

Offset of view into object prior to scroll. Get only. 

SCROLL__LEFT 

int 

r_lef t for scrollbar’s rect. 

SCROLL__L I NE_HE I GHT 

int 

Number of pixels from one line to the next. 

Default: 0. 

SCROLL_MARGIN 

int 

Top margin after scroll, if SCROLL_NORMALIZE TRUE. 

Default: 4. 

SCROLL_MARK 

int 

Position (in client units) undo will go to. Initial value: 0. 

SCROLL_NOTIFY_CLIENT 

caddr_t 

Used by Notifier. 

SCROLL_NORMALIZE 

boolean 

Whether the client wants normalized scrolling. Default: TRUE. 

SCROLLJDBJECT 

caddr_t 

Pointer to the scrollable object. 

SCROLL_OBJECT_LENGTH 

int 

Length of scrollable object, in client units. Default: 0. 

(Value must be > 0). 

SCROLL_PAGE_BUTTONS 

boolean 

Whether the scrollbar has page buttons. Default: TRUE. 

SCROLL_PAGE_BUTTON_LENGTH 

int 

Length in pixels of page buttons. Default: 15. 

SCROLL_PAINT_BUTTONS_PROC 

(procedure) 

Procedure which paints page buttons: 

paint_buttons_j?roc (scrollbar) 

Scrollbar scrollbar; 

Setting the value to NULL resets it to the default button painting 
procedure. 

SCROLL_PIXWIN 

Pixwin * 

Pixwin for scrollbar to write to. 

SCROLL_PLACEMENT 

Scrollbar_setting 

Placement of the bar. 

SCROLL_WEST: vertical bar on left edge 

SCROLL_EAST: vertical bar on right edge 

SCROLL_NORTH: horizontal bar on top edge 

SCROLL_SOUTH: horizontal bar on bottom edge 

Default: SCROLL__WEST or SCROLL_NORTH. 

SCROLL_RECT 

Rect * 

Rect for scrollbar, including buttons. 
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Table 19-25 Scrollbar Attributes—Continued 


Attribute 

Value Type 

Description 

SCROLL_REPEAT_T IME 

int 

The interval, in tenths of a second, that scrolling 

repeats in. This attribute is used only for the initial pressing down 

of the mouse. A value of 0 disables repeat scrolling. Default: 10. 

SCROLL_REQUEST_MOTION 

Scroll_motion 

Scrolling motion requested by user. 

SCROLL_REQUEST_OFFSET 

int 

Pixel offset of scrolling request into scrollbar. Default: 0. 

SCROLL_THICKNESS 

int 

Thickness of bar. Default: 14. 

SCROLL_TO_GRID 

boolean 

Whether the client wants scrolling aligned to multiples 
of SCROLL_LINE__HEIGHT. Default: FALSE. 

SCROLL_TOP 

int 

r_top for scrollbar’s rect. 

SCROLL_VIEW_LENGTH 

int 

Length of viewing window, in client units. Default: 0. 

SCROLL_VIEW_START 

int 

Current offset into scrollable object (client units). 

(Value must be > 0). Default: 0. 

SCROLL_WIDTH 

int 

r width for scrollbar’s recL 
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Table 19-26 Scrollbar Functions 


Definition 

Description 

Scrollbar 

scrollbar__c reate (attributes) 

<attribute-list> a11ributes; 

Creates and returns the opaque handle to a scrollbar. 

int 

scrollbar_destroy(scrollbar) 

Scrollbar scrollbar; 

Destroys scrollbar. 

caddr t 

scrollbar_get(scrollbar, attribute) 

Scrollbar scrollbar; 

Scrollbar attribute attribute; 

Retrieves the value for an attribute of scrollbar. 

int 

scrollbar_set(scrollbar, attributes) 

Scrollbar scrollbar; 

<attribute - list> attributes; 

Sets the value for one or more attributes of scrollbar. 

attributes is a null-terminated attribute list. 

void 

scrollbar_scroll_to(scrollbar, new_view_start) 
Scrollbar scrollbar; 
long new_view_start; 

For programmatic scrolling. Effect is as if the user had 
requested a scroll to new_view_start in the subwin¬ 
dow to which scrollbar is attached. 

int 

scrollbar_paint(scrollbar) 

Scrollbar scrollbar; 

Paints those portions of s c roll bar 
(page buttons, bar proper, and bubble) 
which have been modified since they were last painted. 

int 

scrollbar_paint_clear(scrollbar) 

Scrollbar scrollbar; 

Clears and repaints all portions of scrollbar. 

int 

scrollbar_clear_bubble(scrollbar) 

Scrollbar scrollbar; 

Clears the bubble in scrollbar. 

int 

scrollbar_paint_bubble(scrollbar) 

Scrollbar scrollbar; 

Paints the bubble in scrollbar. 
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Table 19-27 Text Subwindow Attributes 




Attribute 

Value Type 

Description 

TEXTSW_ADJUST_IS_PENDING_DELETE 

boolean 

When TRUE, adjusting a selection causes the selection to be 
pending-delete. Default: FALSE. 

TEXTSW_AGAIN_RECORDING 

boolean 

When FALSE, changes made to the textsw are not repeated when user 
invokes AGAIN. By disabling when not needed (e.g. for program- 
driven error logs) you can reduce memory overhead. Default: TRUE. 

TEXTSW_AUTO_INDENT 

boolean 

When TRUE, a new line is automatically indented to match 
the previous line. Default: FALSE. 

TEXTSW_AUTO__SCROLL__BY 

int 

Number of lines to scroll when type-in moves insert point 
below the view. Default: 1. Create, get. 

TEXT SW_BL INK__CARET 

boolean 

Determines whether the caret blinks. Default: TRUE. 

TEXTSW_BROWSING 

boolean 

When TRUE, prevents editing of the displayed text. If another 
file is loaded in, browsing stays on. Default: FALSE. 

TEXTSW_CHECKPOINT_FREQUENCY 

int 

Number of edits between checkpoints. Set to 0 to 
disable checkpointing. Default: 0. 

TEXTSW_CLIENT_DATA 

char * 

Pointer to arbitrary client data. Default: NULL. 

TEXT SW_CONFIRM_OVERWRITE 

boolean 

A request to write to an existing file will require user 
confirmation. Default: TRUE. 

TEXTSW_CONTENTS 

char* 

Contents of text subwindow. Default: NULL. 

For create and set, specifies the initial contents for non-file textsw. 

Get needs additional parameters: 

window_get (textsw, TEXTSW_CONTENTS, pos, buf, bufjen) 
Return value is next position to read at. 

buf [ 0...buf_len-l ] is filled with the characters from textsw 
beginning at index pos, and is null-terminated only if there 
were too few characters to fill the buffer. 

TEXTSW__CONTROL_CHARS__USE_F ONT 

boolean 

If FALSE, control characters always display as an 
up arrow followed by a character, instead of whatever 
glyph is in the current font. Default: FALSE. 

TEXTSW_DISABLE_CD 

boolean 

Stops textsw from changing current working directory 
(and grays out the associated items in the menu). 

Default: FALSE. 
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Table 19-27 

Text Subwindow Attributes — Continued 

Attribute 

Value Type Description 

TEXTSW_DI SABLE_LOAD 

boolean Prevents files being loaded into the textsw (and grays out 

the associated items in the menu). Default: FALSE. 

TEXTSW_EDIT_COUNT 

int Monotonically incrementing count of the number of edits 

made to the textsw. Get. 

TEXTSW_FILE 

char * File to load. Default: NULL. Create, set. 

TEXTSW_FILE_CONTENTS 

char * initializes the text subwindow contents 

from a file yet still edits the contents in memory. 

TEXTSW_FIRST 

int Zero-based index of first displayed character. 

TEXTSW_FIRST_LINE 

int Zero-based index of first displayed line. 

TEXTSW_HISTORY_LIMIT 

int Number of user action sequences that can be undone. 

Default: 50. Create, get. 

TEXTSW_IGNORE_LIMIT 

int Number of edits textsw allows before vetoing destroy. Valid values 

are 0, meaning destroy will be vetoed if any edits have been done, and 
TEXTSW INFINITY, meaning destroy will never be vetoed. Default: 
0 . 

TEXTSW_INSERT_FROM_FILE 

string inserts the contents of a file into 

a text subwindow at the current insertion point. 

TEXTSW_INSERT_MAKES_VISIBLE 

Textsw_enum Controls whether insertion causes repositioning to make 

inserted text visible. Possible values are TEXTSW_ALWAY S, 
TEXTSW_NEVER and TEXTSW_IF_AUTO_SCROLL. 

Default: TEXTSW_IF_AUTO_SCROLL. 

TEXTSW_INSERTION_POINT 

Textsw_index Index of the current insertion point. Get, set. 

TEXTSW_LEFT_MARGIN 

int Number of pixels in the margin on left. Default: 4. Create, get. 

TEXTSW_LENGTH 

int Length of the textsw’s contents. Get only. 

TEXT SW_LINE_BREAK_ACTION 

Textsw_enum Determines how the textsw treats file lines too big 

to fit on one display line. Possible values are either 

TEXTSW_CLIP or TEXTSW_WRAP_AT_CHAR. 

Default: TEXTSW_WRAP_AT_CHAR. Create, set. 

TEXTSW_LOWER_CONTEXT 

int Minimum # of lines to maintain between insertion point 

and the bottom of view. Used by auto scrolling when type-in 
would disappear off bottom of view. 

-1 means defeat auto scrolling. Default: 2. 
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Table 19-27 

Text Subwindow Attributes — Continued 

Attribute 

Value Type 

Description 

TEXTSW_MEMORY_MAXIMUM 

int 

How much memory to use when not editing files. This attribute only 
takes effect at textsw window creation time or after the window has 
been reset via textsw_reset(). The lower bound of the attribute is 1000 
bytes which is silently enforced. Default: 20,000 bytes. (If a great 
deal of text will be inserted into the text subwindow, either by the pro¬ 
gram or the user, you may need to increase this.) 

TEXTSW_MENU 

Menu 

The text subwindow’s menu. Get, set. 

TEXTSW_MODIFIED 

boolean 

Whether or not the textsw has been modified. Get only. 

TEXTSW_MULTI_CLICK_SPACE 

int 

Max # of pixels that can be between successive mouse clicks 
and still have the clicks be considered a multi-click. Default: 3. 

TEXTSW_MOLTI_CLICK_TIMEOUT 

int 

Max # of milliseconds that can be between successive 

mouse clicks and still have the clicks be considered 

a multi-click. Default: 390. 

TEXTSW_NOTIFY__PROC 

(procedure) 

Notify procedure. Form is: 

void 

not if y_j?roc (textsw, avlist) 

Textsw textsw 

Attr_avlist avlist 

Default: NULL, meaning standard procedure. 

TEXTSW__READ_ONLY 

boolean 

When TRUE, prevents editing of the displayed text. If another file 
is loaded in, READ_ONLY is turned off again. Default: FALSE. 

TEXTSW_SCROLLBAR 

Scrollbar 

Scrollbar to use for text subwindow scrolling. 

NULL means no scrollbar. 

Default: A scrollbar with default attributes. 

Note: text subwindow has a scrollbar by default, so you would 
only use this to get no scrollbar, or to get the scrollbar handle. 

TEXTSW_STATUS 

Textsw_status * 

If set, specifies the address of a variable of type 

Textsw status into which a value is written that reflects 
what happened during the call to window_create(). 

(For possible values, see the Textsw_status Values table). 

TEXT SW_STORE_CHANGE S_F ILE 

boolean 

If TRUE, Store changes the file being edited to that named 
as the target of the Store. If FALSE, Store does not affect 
which file is being edited. Default: TRUE. 

TEXTSW_STORE_SELF_I S_SAVE 

boolean 

Causes textsw to interpret a Store to the name of the current file 
as a Save. Default: FALSE. Create, get. 
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Table 19-27 

Text Subwindow Attributes — Continued 

Attribute 

Value Type 

Description 

TEXTSW__UP DATE__SCROLLBAR 

(no value) 

Causes text subwindow to update the bubble in the scrollbar. 

Set only — get returns NULL. 

TEXTSW_UPPER_CONTEXT 

int 

Min # of lines to maintain between the start of the selection and 
top of view. -1 means to defeat the normal actions. Default: 2. 
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Table 19-28 Textsw_ 

action Attributes 

Attribute 

Value Type 

Description 

TEXT SW_ACTION_CAPS_LOCK 

boolean 

The user pressed the CAPS-lock function key to change the 
setting of the CAPS-lock (it is initially 0, meaning off). 

TEXTSW_ACTION_CHANGED_DIRECTORY 

char * 

The current working directory for the process has been 
changed to the directory named by the provided string value. 

TEXTSW_ACTIONJEDITED_FILE 

char * 

The file named by the provided string value has been edited. 
Appears once per session of edits (see below). 

TEXTSW_ACTION_EDITED_MEMORY 

none 

monitors whether an empty text subwindow has been edited. 

TEXTSW_ACTION_FILE_IS_READONLY 

char * 

The file named by the provided string value does not have 
write permission. 

TEXTSW_ACTION_LOADED_FILE 

char * 

The text subwindow is being used to view the file named 
by the provided string value. 

TEXTSW_ACTION_TOOL_CLOSE 

(no value) 

The frame containing the text subwindow should become 

iconic. 

TEXTSW_ACTION_TOOL_DESTROY 

Event * 

The tool containing the text subwindow should exit, 
without checking for a veto from other subwindows. 

The value is the user action that caused the destroy. 

TEXTSW_ACTION_TOOL_QOIT 

Event * 

The tool containing the text subwindow should exit 
normally. The value is the user action that caused 
the exit. 

TEXT SW_ACTION_TOOL_MGR 

Event * 

The tool containing the text subwindow should do the 
window manager operation associated with the 
provided event value. 

TEXT SW_ACTION_USING_MEMORY 

(no value) 

The text subwindow is being used to edit a string stored in 
primary memory, not a file. 
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Table 19-29 Textsw status Values 


Value 

Description 

TEXTSW_STATUS_OKAY 

The operation encountered no problems. 

TEX T SW_S TAT U S_BAD_AT TR 

The attribute list contained an illegal or unrecognized attribute. 

TEXT SW_S TATU S_BAD_AT TR_VALUE 

The attribute list contained an illegal value for an attribute, 
usually an out of range value for an enumeration. 

TEXTSW_STATUS_CANNOT_ALLOCATE 

A call to calloc(2) or malloc(2) failed. 

TEXTSW STATUS_CANNOT_OPEN_INPUT 

The specified input file does not exist or cannot be accessed. 


TEXTSW STATUS_CANNOT_INSERT_FROM_FILE The operation encountered a problem when trying 



to insert from file. 

TEXTSW_STATUS_OUT_OF_MEMORY 

The operation ran out of memory while editing in memory. 

TEXTSW_STATUS_OTHER_ERROR 

The operation encountered a problem not covered by any of 
the other error indications. 
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Table 19-30 Text Subwindow Functions 




Definition 

Description 

Textsw_mark 

textsw_add_mark(textsw, position, flags) 

Textsw textsw; 

Textsw__index position; 
unsigned flags; 

Adds a new mark at position. 

flags can be either TEXTSW_MARK_DEFAULTS or 

TEXT SW_MARK_MOVE_AT_INSERT. 

int 

textsw append__file__name (textsw, name) 

Textsw textsw; 

char *name; 

Returns 0 if textsw is editing a file, 

and if so appends the name of the file at the end of name. 

Textsw__index 

textsw_delete(textsw, first, last_plus_one) 

Returns 0 if the operation fails. 

Removes the span of characters beginning with first, 

Textsw textsw; 

Textsw__index first, last_plus__one; 

and ending one before last_plus__one. 

Textsw_index 

textsw_edit(textsw, unit, count, direction) 

Textsw textsw; 

unsigned unit, count, direction; 

Returns 0 if the operation fails. Erases a character, word or 
line, depending on whether unit is SELN_LEVEL_FIRST, 
SELN_LEVEL_FIRST+l, or SELN_LEVEL_LINE. If 
direction is 0, characters after the insertion point are 
affected, otherwise characters before the insertion point are 
affected. The operation will be done count times. 

Textsw_index 

textsw_erase(textsw, first, last_plus_one) 

Textsw textsw; 

Textsw_index first, last_plus_one; 

Returns 0 if the operation fails. 

Equivalent to text sw__delete () ,but does not 
affect the global shelf. 

void 

textsw_f ile_lines__visible (textsw, top, bottom) 

Textsw textsw; 

int *top, *bottom; 

Fills in top and bottom with the file line indices of 
the first and last file lines being displayed in textsw. 

int 

textsw_find_bytes(textsw, first, last_plus_one, 
buf, buf_len, flags) 

Textsw textsw; 

Textsw index *first, *last j>lus_one; 

char *buf; 

unsigned buf_len, flags; 

Beginning at the position addressed by first, searches for the 
pattern specified by buf of length buf_len. Searches 
forwards if flags is 0, else searches backwards. 

Returns -1 if no match, else matching span placed in 
indices addressed by first and last_plus_one. 
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Table 19-30 Text Subwindow Functions — Continued 


Definition 

Description 

Textsw index 

textsw_find_mark(textsw, mark) 

Textsw textsw; 

Textsw_mark mark; 

Returns the current position of mark. If 

this operation fails, it will return TEXTS W_INFINITY. 

Textsw 

textsw_first(textsw) 

Textsw textsw; 

Returns the first view into textsw. 

Textsw_index 

textsw_index_for_file_line(textsw, line) 

Textsw textsw; 

int line; 

Returns the character index for the first 
character in the line given by line. If this operation 
fails, it will return TEXTSW_CANNOT_SET. 

Textsw_index 

textsw_insert(textsw, buf, buf len) 

Textsw textsw; 

char *buf; 

int buf_len; 

Inserts characters in buf into textsw 
at the current insertion point. 

The number of characters actually inserted 
is returned — this will equal buf_len 
unless there was a memory allocation failure. 

If there was a failure, it will return 0. 

textsw_match_bytes(textsw, first, last_plus one, 
start_sym, start_sym_len, 

Searches for a block of text in the textsw’s contents 
which starts with characters matching start_sym and 


end_sym, end_sym_len, field_flag) ends with characters matching end_sym. 


Textsw textsw; 

Textsw_index *first, *last_plus_one; 
char *start_sym, *end_sym; 

int start_sym_len, end_sym_len; 

unsigned field_flag; 

This function places the starting index of the matching block in 
first and its ending index in last. 

Textsw 

textsw_next(textsw) 

Textsw textsw; 

Returns the next view in the set of views into text sw. 

void 

textsw_normalize_view(textsw, position) 

Textsw textsw; 

Textsw_index position; 

Repositions the text so that the character 
at position is visible and at the top of the subwindow. 

void 

textsw_possibly_normalize(textsw, position) 

Textsw textsw; 

Textsw__index position; 

If the character at position is already visible, this function 
does nothing. If it is not visible, it repositions the text 
so that it is visible and at the top of the subwindow. 
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Table 19-30 Text Subwindow Functions — Continued 


Definition 

Description 

void 

textsw remove_mark(textsw, mark) 

Textsw textsw; 

Textsw_mark mark; 

Removes an existing mark from textsw. 

Textsw_index 

textsw replace_bytes(textsw, first, 

la st_plu s_one, 
buf, buf__len) 

Textsw textsw; 

Textsw_index first; 
char *buf; 

unsigned buf___len; 

Replaces the character span from first to 
last_plus_one by the characters in buf. 
last plus one. The return value is the net 
number of bytes inserted. The number is negative if the 
original string is longer than the one that replaces it If 
this operation fails, it will return a value of 0. 

void 

textsw_reset(textsw, x, y) 

Textsw textsw; 

int x, y; 

Discards edits performed on the contents of textsw. 

If needed, a message box will be displayed at x, y. 

unsigned 

textsw_save(textsw, x, y) 

Textsw textsw; 

int x, y; 

Saves any edits made to the file currently 
loaded into textswJf needed, a message box 
will be displayed at x, y. 

int 

textsw screen_line_count (textsw) 

Textsw textsw; 

Returns the number of screen lines in textsw. 

void 

textsw scroll_lines(textsw, count) 

Textsw textsw; 

int count; 

Moves the text up or down by count lines. If count 
is positive, then the text is scrolled up on the screen, 

(forward in the file); if negative, the text is scrolled down, 
(backward in the file). 

void 

textsw_set_selection(textsw, first, last_plus_one, 

type) 

Textsw textsw; 

Textsw index first, last_plus_one; 
unsigned type; 

Sets the selection to begin at first and include all 
characters up to last_plus_one. 
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Table 19-30 Text Subwindow Functions — Continued 


Definition 

Description 

unsigned 

textsw_store_file(textsw, filename, x, y) 

Stores the contents of textsw 

Textsw textsw; 

to the file named by filename. If needed, a 

char *filename; 

message box will be displayed at x, y. 

int x, y; 
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Table 19-31 TTY Subwindow Attributes 


Attribute 

. 

Type 

. ... 

Description 

TTY_ARGV 

char ** 

Argument vector: name of the pro¬ 
gram running in the tty subwindow, 
followed by arguments for that pro¬ 
gram. 

TTY_CONSOLE 

boolean 

If TRUE, tty subwindow is con¬ 
sole. Set only. Default: FALSE. 

TTY_PAGE_MODE 

boolean 

If TRUE, output will stop after 
each page. Default: FALSE. 

TTY_QU I T_ON_CH I LD_DEATH 

boolean 

If TRUE, window_done () is 
called on the subwindow when its 
child terminates. Set only. Default: 

FALSE. 


Table 19-32 TTY Subwindow Functions 


Definition 

Description 

int 

ttysw_input(tty, buf, len) 

Tty tty; 

char *buf; 

Appends len number of characters from buf 
onto tty’s input queue. It returns the number 
of characters accepted. 

int len; 


int 

ttysw_output(tty, buf, len) 

Tty tty; 

char *buf; 

int len; 

Appends len number of characters from buf 
onto tty’s output queue, i.e. they are sent 
through the terminal emulator to the TTY. It 
returns the number of characters accepted. 
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Table 19-33 TTY Subwindow Special Escape Sequences 


' _ _ 


Escape Sequence 103 

Description 

\E [It 

open frame. 

\E[2t 

close frame. 

\E[3t 

move frame with interactive feedback. 

\E[3;TOP;LEFTt 

move frame to location specified by (TOP,LEFT). 

\E[4t 

resize frame with interactive feedback. 

\E[4;WIDTH;HEIGHTt 

resize frame to WIDTH and HEIGHT. 

\E[5t 

expose. 

\E[6t 

hide. 

\E[7t 

redisplay. 

\E[8;ROWS;COLSt 

resize frame so its width and height are ROWS and COLS. 

\E[lit 

report if frame is open or closed by sending \ [ It or \ [2t, respectively. 

\E[13t 

report frame’s position by sending the \E [ 3; TOP;LEFT t sequence. 

\E[14t 

report frame’s size in pixels by sending the \E [ 3 ; WIDTH; HEIGHT t sequence. 

\E [ 18t 

report frame’s size in characters by sending the \E [ 8 ;ROWS; COLS t sequence. 

\E[20t 

report the frame icon’s label by sending the \E [Llabel\E\ sequence. 

\E[21t 

report frame’s label by sending the \E] llabel\E\ sequence. 

\E] ltext\E\ 

set frame’s label to text. 

\E]Ifile\E\ 

set frame’s icon to the icon contained in file. 

\E]Llabel\E\ 

set icon’s label to label. 

\E [>OPTl; . . .OPTrih 

turn requested options on. The only currently defined option is 1, for TTY_PAGE_MODE. 

\E [>OPTl; . .OPTnk 

turn requested options off. 
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Table 19-33 

TTY Subwindow Special Escape Sequences — Continued 

Escape Sequence 103 

Description 

\E [>OPTl; . . .OPTnl 

report current option settings by sending \E [>OPTxl or \E>OPTh for each option*. 


103 In this table “\E” denotes the <ESC> character, as it does in termcap. 
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Table 19-34 

Window Attributes 


Attribute 

Value Type 

Description 

WIN_BELOW 

Window 

Causes the window to be laid out below window given as the value. 

WIN_BOTTOM_MARGIN 

int 

Margin at bottom of window. 

WIN_CLIENT_DATA 

caddr_t 

Client’s private data — for your use. 

WIN_COLUMNS 

int 

Window’s width (including left and right margins) in columns. 

WIN_COLUMN_GAP 

int 

Gap between columns in the window. 

WIN_COLUMN_WIDTH 

int 

Width of a column in the window. 

WI N__C ON S UME_KBD_E VENT 

short 

Window will receive this event. 

WIN_CONSUME_KBD_EVENTS 

list of short 

Null terminated list of events window will receive. Create, set. 

WIN_CONSUME_PICK_EVENT 

short 

Window will receive this pick event. 

WIN_CONSUME_PICK_EVENTS 

list of short 

Null terminated list of pick events window will receive. Create, set. 

WIN_CURSOR 

Cursor 

The window’s cursor. Note: the pointer returned by 
window_get () points to per-process static storage. 

WINJDEVICE_NAME 

char * 

UNIX device name associated with window, consisting of a string and 
numeric part, e.g. win 10. Get only. 

WIN_DEVICE_NUMBER 

int 

Numeric component of device name. Get only. 

WIN_ERROR_MSG 

char * 

Error message to print before exit(l). Create only. 

WI N_E VEN T_P ROC 

(procedure) 

Client’s callback procedure which receives input events: 

Notify_value 

event__proc (window, event, arg) 

Window window; 

Event *event; 
caddr_t arg; 

WI N_EVENT_ST ATE 

short 

Gets the state of the specified event code. For buttons and keys, 
zero means “up,” non-zero means “down.” Get only. 

WIN_FD 

int 

The UNIX file descriptor for the window. Get only. 

WIN_FIT_HEIGHT 

int 

Causes window to fit its contents in the height dimension, 
leaving a margin specified by the value given. 
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Table 19-34 

Window Attributes- 

— Continued 

Attribute 

Value Type 

Description 

WIN_FIT_WIDTH 

int 

Causes window to fit its contents in the width dimension, 
leaving a margin specified by the value given. 

WIN_FONT 

Pixfont * 

The window’s font. Notes for the current release: 

tty subwindows don’t use WIN_FONT. Frames don’t use WIN_FONT 

to render their labels; however, they do use WIN_FONT 

in calculating WIN_COLUMNS and WIN_ROWS. Setting WIN_FONT 

does not cause the default system font to be set. 

WI N_GRAB_ALL_INPUT 

boolean 

Window will get all events regardless of location. 

WIN_HEIGHT 

int 

Window’s height in pixels. Value of WIN_EXTEND_TO_EDGE 
causes subwindow to extend to bottom edge of frame. 

Default: WI N_EXTEND_T0_EDGE. 

WIN_HORIZONTAL_SCROLLBAR 

Scrollbar 

Horizontal scrollbar. 

WI N_I GNORE_KBD_EVENT 

short 

Window will not receive this event. 

WI N_I GNORE_KBD_EVENT S 

list of short 

Null terminated list of events window will not receive. Create, set. 

WI N_I GNORE_P I CK_EVENT 

short 

Window will not receive this pick event. 

WI N_I GNOREJ? I CK_EVENTS 

list of short 

Null terminated list of pick events window will not receive. Create, set. 

WIN_INPUT_DESIGNEE 

int 

Window which gets events this window doesn’t consume. (Note that 
the value must be the WIN_DEVICE_NUMBER of the designee). 

WIN_KBD_FOCUS 

boolean 

Whether or not the window has the keyboard focus. 

WIN_KBD_INPUT_MASK 

Inputmask * 

Window’s keyboard inputmask. Note: the pointer returned by 
window_get () points to per-process static storage. 

WI N_LEFT_MARGI N 

int 

Margin at left of window. 

WIN_MENU 

Menu 

Window’s menu. Note: In the current release this doesn’t work for 
panels or tty subwindows. 

WI N_MOUSE_XY 

int, int 

Mouse’s position within the window. Set only. 

WIN_NAME 

char * 

Name of window (currently unused by SunView). 

WIN_OWNER 

Window 

Owner of window. Get only. 

WIN_PERCENT_HEIGHT 

int 

Sets a subwindow’s height as a percentage of the frame’s height. 
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Table 19-34 Window Attributes — Continued 


Attribute 

Value Type 

Description 

WIN_PERCENT_WIDTH 

int 

Sets a subwindow’s width as a percentage of the frame’s width. 

WIN_PICK_INPUT_MASK 

Inputmask * 

Window’s pick inputmask. Note: the pointer returned by 
window_get () points to per-process static storage. 

WIN_PIXWIN 

Pixwin * 

The window’s pixwin. Get only. 

WIN_RECT 

Rect* 

Rect of the window. For frames, same as FRAME_OPEN_RECT. 

Note: the pointer returned by window_get () for this attribute 
points to per-process static storage. 

WIN_RIGHT_MARGIN 

int 

Margin at right of window. 

WIN_RIGHT_OF 

Window 

Causes the window to be laid out just to the 
right of the window given as the value. 

WIN_ROW_GAP 

int 

Gap between rows in the window. 

WIN_ROW_HEIGHT 

int 

Height of a row in the window. 

WIN_ROWS 

int 

Window’s height (including top and bottom margins) in rows. 

WIN_SCREEN_RECT 

Rect* 

Rect of the screen containing the window. Get only. 

Note: the pointer returned by window_get () for this attribute 
points to per-process static storage. 

WIN_SHOW 

boolean 

Causes the window to be displayed or undisplayed. 

WI N_T OP_MARG IN 

int 

Margin at top of window. 

WIN_TYPE 

Window_type 

Type of window. One of FRAME_TYPE, PANELJTYPE, 

CANVASJTYPE, TEXTSWJTYPE or TTY_TYPE. Get only. 

WIN_VERTICAL_SCROLLBAR 

Scrollbar 

Vertical scrollbar. 

WIN_WIDTH 

int 

Window’s width in pixels. Value of WIN_EXTEND_TO_EDGE 
causes subwindow to extend to right edge of frame. 

Default: WIN_EXTEND_T0_EDGE. 

WIN_X 

int 

x position of window, relative to owner. 

WIN_Y 

int 

y position of window, relative to owner. 
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Table 19-35 

Frame Attributes 


Attribute 

Value Type 

Description 

FRAME_ARGS 

int, char ** 

Interpret command line arguments. Strips -W command-line frame 
arguments out of argv. Create only. 

FRAME_ARGC_PTR_ARGV 

int *, char ** 

Interpret command line args. Strips -W command-line frame argu¬ 
ments out of argv, and decrements argc accordingly. Create only. 

FRAME_BACKGROUND_COLOR 

struct singlecolor * 

Background color. 

FRAME_CLOSED 

boolean 

Whether frame is currently closed. 

FRAME_CLOSED_RECT 

Rect * 

Frame’s rect when closed. 

FRAME_CMDL I NE_HELP_P ROC 

(procedure) 

Called when user types the command-line argument -WH. Default: 
frame cmdline__help (program_name) 
char *program_name; 

FRAME_CURRENT_RECT 

Rect * 

Returns either FRAME_OPEN_RECT or FRAME_CLOSED_RECT, 
depending on the value of FRAME__CLOSED. 

Note: in the current release, there is a bug in the behavior 
of FRAME CURRENT_RECT for subframes. It is set relative 
to the owner frame, but it is retrieved relative to the screen. 

FRAME_DEFAULT_D ONE_P ROC 

(procedure) 

Default value of FRAME_DONE JPROC. Get only. 

The default procedure is to set the subframe to WIN_SHOW, FALSE. 

FRAME_DONE_P ROC 

(procedure) 

Client’s proc called when user chooses ‘Done’ from subframe’s menu: 
done_proc(frame) 

Frame frame; 

FRAME_EMBOLDEN_LABEL 

boolean 

If TRUE, frame’s label is rendered in bold. 

FRAME_FOREGROUND_COLOR 

struct singlecolor * 

Foreground color. 

FRAME_ICON 

Icon 

The frame’s icon. 

FRAME_INHERIT__COLORS 

boolean 

If TRUE, colormap of frame is inherited by subwindows. 

FRAME_LABEL 

char * 

The frame’s label. 

FRAME_NO_CONFIRM 

boolean 

Set to TRUE before destroying a frame 
to defeat confirmation. Set only. 

FRAME_NTH_SUBFRAME 

int 

Returns frame’s nth (from 0) subframe. Get only. 
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Table 19-35 

Frame Attributes — Continued 

Attribute 

Value Type 

Description 

FRAME_NTH_SUBWI NDOW 

int 

Returns frame’s nth (from 0) subwindow. Get only. 

FRAME_NTH_WINDOW 

int 

Returns frame’s nth (from 0) window, regardless of whether 
the window is a frame or a subwindow. Get only. 

FRAME_OPEN_RECT 

Rect * 

Frame’s rect when open. 

FRAME__SHOW__LABEL 

boolean 

Whether the label is shown. Default: 

TRUE for base frames, FALSE for subframes. 

FRAME_SUBWINDOWS_ADJUSTABLE 

boolean 

User can move sub window boundaries. Default: TRUE. 
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Table 19-36 Window Functions and Macros 


:• ................................................................... ................................. 

I........................ 

Definition 

Description 

void 

Queries the user defaults database 

window_bell(win) 

Window win; 

to see if the user wants the bell to be 

sounded, the window to be flashed, or both. 

Window 

window create(owner, type, attributes) 

Window owner; 

Kwindow type> type; 

<attribute-list> att ribute s; 

Creates a window and returns its handle, 
type is one of FRAME, PANEL 

TEXTSW, TTY, or CANVAS. 

void 


window default__event_j?roc (window, event, arg) 
Window window; 

Event *event; 

caddr t arg; 

Calls the default event procedure. 

The arguments passed in are the window (canvas or panel), 
the event, and an optional argument pertaining to the event. 

window_destroy (win) 

Window win; 

Destroys win, and any sub windows or 
subframes owned by win. 

window done(win) 

Window win; 

Destroys the entire hierarchy to which win belongs. 

window_fit(win) 

Window win; 

Causes win to fit its contents 

in both dimensions. A macro, defined as: 
window__set (win, WINJFIT, 0, 0). 

window fit_height(win) 

Window win; 

Causes win to fit its contents 

in the vertical dimension. A macro, defined as: 
window_set (win, WIN_FIT_HEIGHT, 0, 0). 

window fit width(win) 

Window win; 

Causes win to fit its contents 

in the horizontal dimension. A macro, defined as: 
window_set(win, WIN_FIT_WIDTH, 0, 0). 

caddr_t 

window_get(win, attribute) 

Window win; 

Window attribute attribute; 

Retrieves the value of an attribute for win. 
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Table 19-36 Window Functions and Macros — Continued 


Definition 

Description 

caddr__t 

window_loop(subframe) 

Frame subframe; 

Causes subframe to be displayed, and receive all 
input. The call will not return until window__return () 
is called from one of the application’s notify procs. 

void 

window_main__loop (base_f rame) 

Frame base_frame; 

Displays base_f rame on the screen and begins the 
processing of events by passing control to the Notifier. 

int 

window_read_event(window, event) 

Window window; 

Event *event; 

Reads the next input event for window. 

In case of error, sets the global variable errno 
and returns -1. 

void 

window_refuse_kbd_focus (window) 

Window window; 

When your event handler receives a KBD_REQUEST 
event, call this function if you do not want your 
window to become the keyboard focus. 

void 

window_release_event_lock (window) 

Window window; 

Releases the event lock, allowing other processes to receive input. 

void 

window_return(value) 
caddr_t value; 

Usually called from one of the application’s panel item 
notify procs. Causes window_loop () to return. 

window set (win, attributes) 

Window win; 

<attribute-list> attributes; 

Sets the value of one or more of win’s attributes. 

attributes is a null-terminated attribute list. 
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Table 19-37 Command Line Frame Arguments 

Flag 

Long Flag 

Arguments 

Corresponding Attributes 

-Wb 

-background_color 

red green blue 

FRAME_BACKGROUND_COLOR 

-Wh 

-height 

lines 

WIN_ROWS 

-WH 

-help 

— 

(Causes FRAME_CMDLINE_HELP_PROC to be called.) 

-Wf 

-foreground color 

red green blue 

FRAME_FOREGROUND_COLOR 

-Wg 

. -set__default_color 

— 

FRAME_INHERIT_COLORS, TRUE 

-Wi 

-iconic 

— 

FRAME_CLOSED, TRUE 

-WI 

-icon__image 

filename 

ICON__IMAGE of frame’s icon 105 

-WI 

-label 

label 

FRAME_LABE L 

-WL 

-icon_label 

label 

ICON_LABEL of frame’s icon 

-Wn 

-no_JLabel 

— 

FRAME_SHOW_LABEL, FALSE 

-Wp 

-position 

xy 

WIN_X, WIN_Y 

-WP 

-icon__position 

xy 

FRAME_CLOSED_RECT 

-Ws 

-size 

xy 

WIN__WIDTH, WIN_HEIGHT 

-Wt 

-font 

filename 

(Sets system default font) 

-WT 

-icon__font 

filename 

ICON_FONT of frame’s icon 

-Ww 

-width 

columns 

WIN_COLUMNS 






105 The -WI option will not work if the application’s code does not already specify its icon. 
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Source Available 


A.l. filer 


A 

Example Programs 


If the appropriate optional software category has been installed or mounted on 
your system, the source code for some of these examples programs is available 
on-line in /usr/share/src/sun/suntool/examples. In addition, the 
directory above this (/usr/share/src/sun/suntool) contains the source 
for many of the SunView 1 programs in the SunOS, such as textedit, 
perfmeter, and iconedit. 


This program is discussed in Chapter 4, Using Windows. It displays a listing in a 
tty subwindow, which the user manipulates through panel items. 

If the user presses the [ Prons I key in the panel, or chooses ‘Props’ from the frame 
menu, or pushes the Set Is flags button, a pop-up subframe appears, filer uses the 
Selection Service to determine what file name the user has selected, and creates a 
pop-up text subwindow where that file is displayed. 

filer uses the alerts package to ask the user for confirmation and put up messages. 
It also includes old code which mimics alerts by using window_loop () to put 
up a subframe, but programs written for SunOS Release 4.0 and beyond in gen¬ 
eral will have no need for this. 
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/*****************************************************************************/ 
/* 4.0 filer.c */ 

/*****************************************************************************/ 


#include <suntool/sunview.h> 

#include <suntool/panel.h> 

#include <suntool/tty.h> 

#include <suntool/textsw.h> 

#include <suntool/seln.h> 

#include <suntool/alert.h> 

#include <sys/stat.h> /* stat call needed to verify existence of files */ 


/* these objects are global so their attributes can be modified or retrieved */ 
Frame base_frame, edit_frame, ls_flags_frame; 

Panel panel, ls_flags__panel; 

Tty ttysw; 

Textsw editsw; 

Panel_item dir_item, fname_item, filing_mode_item, done_item; 

int quit_conf irmed_from_j?anel; 


#define 
#define 


MAX_FILENAME_LEN 
MAX PATH LEN 


256 

1024 


char *getwd(); 


main (argc, argv) 
int argc; 
char **argv; 

{ 

static Notify_value filer_destroy_func(); 
void ls_flags_proc () ; 


base_frame = window__create (NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "filer”, 

FRAME_PROP S_ACT 10N_PR0C, 1 s_f lags_j?roc, 

FRAME_PROPS_ACTIVE, TRUE, 

FRAME_N0_C0NFIRM, TRUE, 

0 ); 

(void) notify_interpose_destroy_func (base_frame, filer_destroy__func) ; 


create_panel_subwindow () ; 
create__tty_subwindow () ; 
create_edit_popup () ; 
create_ls_f lags_popup () ; 
quit__conf irmed_f rom_j>anel = 0; 

window_main__loop (base_frame) ; 
exit (0); 

} 

create__tty_subwindow () 

{ 

ttysw = win do w__c reate (base_frame, TTY, 0) ; 

} 

create_edit_popup () 

{ 
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r 


edit__frame = window_create (base 

_frame, FRAME, 



FRAME SHOW LABEL, 

TRUE, 



0); 



} 

editsw = window__create (edit_f rame, TEXTSW, 0); 


ere 

{ 

ate_j?anel_subwindow () 



void ls_proc() , ls_flags_j?roc () 

, quit_proc(), edit_proc (), 



edit_sel_proc(), del_proc() 

/ 



char current_dir [MAX_PATH__LEN]; 




panel = window_create(base_frame, PANEL, 0); 



(void) panel_create_item(panel, 

PANEL_BUTTON, 



PANEL LABEL_X, 

ATTR_COL(0), 



PANEL LABEL Y, 

ATTR_ROW(0), 



PANEL_LABE L_IMAGE, 

panel_button_image(panel, "List Directory", 0, 0), 



PANEL NOTIFY_PROC, 

ls_proc. 



0); 




(void) panel_create__item (panel, 

PANEL_BUTTON, 



PANE L_L ABE L_I MAGE, 

panel_button_image(panel, "Set Is flags", 0, 0), 



PANEL NOTIFY_PROC, 

ls_f lags_proc. 



0); 




(void) panel_create__item(panel. 

PANEL_BUTTON, 



PANE L_L ABE L_I MAGE, 

panel_button_image(panel, "Edit", 0, 0), 



PANEL NOTIFY PROC, 

edit _p roc. 



0); 




(void) panel_create_itern (panel, 

PANEL_BUTTON, 



P ANEL_LABE L__I MAGE, 

panel_button_image(panel, "Delete", 0, 0), 



PANEL_N OTIFY_PROC, 

del_proc. 



0); 

* 



(void) panel_create_itern(panel. 

PANEL_BUTTON, 



PANEL_LABEL_IMAGE, 

panel_button_image(panel, "Quit", 0, 0), 



PANEL_NOTIFY_PROC, quit_proc. 



0); 




filing mode_item = panel__create 

item(panel, PANEL_CYCLE, 



PANE L_LABE L_X, 

ATTR_C0L(0) , 



PANE L_LABE L_Y, 

ATTR_ROW(1) , 



PANEL_LABEL_STRING, 

"Filing Mode:", 



PANEL_CHOICE_STRINGS, 

"Use \"File:\" item", 
t'Use Current Selection", 0, 



0); 




(void) panel_create_item(panel, 

PANE L_ME S SAGE, 



PANE L_LABE L__X, 

ATTR_COL(0) , 



PANE L_LABE L_Y, 

ATTR_ROW(2), 



0); 




dir item = panel_create_item(panel, PANEL_TEXT, 



PANE L_LABE L_X, 

ATTR_COL(0), 

V_ 


PANE L_LABE L_Y, 

ATTR_ROW (3), 

_ t 
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(— 


PANEL VALUE DISPLAY_LENGTH, 

60, 





PANEL__VALUE, 

getwd(current_dir), 





PANEL_LABEL_STRING, 

"Directory: ", 





0); 






fname__item = panel__create_item (panel, PANEL_TEXT, 





PANE L_LABE L_X, 

ATTR__C0L (0) , 





PANEL__LABEL_Y, 

ATTR_R0W(4), 





PANEL_LABEL_DISPLAY_LENGTH, 

60, 





PANEL LABEL STRING, 

"File: ", 





0); 






window__fit_height (panel) ; 





} 

window_set (panel, PANEL__CARET_ITEM, fname_item, 0); 




create_ls_flags_popup () 

/ 






void done_proc(); 






ls_flags_frame = window__create (base_frame, FRAME, 0); 





ls_flags_panel = window__create (ls_ 

_flags_frame, PANEL, 0); 





panel_create_item(ls_f lags_panel. 

PANEL_MESSAGE, 





PANEL_ITEM_X, 

ATTR__C0L (14) , 





PANEL_ITEM_Y, 

ATTR__R0W (0) , 





PANEL_LABEL_STRING, 

"Options for Is command". 





PANEL CLIENT DATA, 

H ii 

t 





0); 






panel__create_item(ls_flags_panel. 

PANEL_CYCLE, 





PANEL_ITEM_X, 

ATTR_C0L(0) , 





PANEL_ITEM_Y, 

ATTR_R0W(1), 





PANEL_D I SPLAY_LEVEL, 

PANEL_CURRENT, 





PANEL_LABEL_STRING, 

"Format: 

ii 

r 




PANE L_CH01CE_STRINGS, 

"Short", "Long", 0, 





PANEL CLIENT_DATA, 

i. 1 ", 





o 






pan e l_c r e a t e__i t em (1 s_f 1 a g s_j>a ne 1, 

PANEL_CYCLE, 





PANEL_ITEM_X, 

ATTR__C0L (0) , 





PANEL_ITEM_Y, 

ATTR_R0W(2), 





PANE L_D ISP LA Y__LEVEL, 

PANEL__CURRENT, 





PANEL_LABEL_STRING, 

"Sort Order: 

ii 

r 




PANEL_CH0ICE_STRINGS, 

"Descending", "Ascending", 0, 





PANE L_CL I ENT_D ATA, 

ii r ii 

r 





o 






panel_create_item(ls_flags_panel. 

PANE L_CY CLE, 





P ANEL__I TEM_X, 

ATTR_C0L(0) , 





PANEL__ITEM_Y, 

ATTR_R0W(3), 





PANEL_D I SPLAY_LEVEL, 

PANEL_CURRENT, 





PANEL_LABEL_STRING, 

"Sort criterion: 

ii 

r 




PANE L_CH01CE_STRINGS, 

"Name", "Modification Time", 
"Access Time", 0, 





PANEL CLIENT DATA, 

r+ 

d 





0); 
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/ 


panel_create_item(ls_flags _j?anel. 

PANE L_CY CLE, 




PANEL_ITEM_X, 

ATTR_C0L(0) , 




PANEL_ITEM_Y, 

ATTR_R0W(4) , 




PANEL DISPLAY LEVEL, 

PANEL CURRENT, 




PANEL LABEL STRING, 

"For directories, list: ", 




PANEL_CHOICE_STRINGS , 

"Contents", "Name Only", 0, 




PANE L_CL I ENT_D ATA, 

" d ", 




0); 





panel_creat e_item (1 s_f lags_panel, 

PANE L_CY CLE, 




PANEL_ITEM_X, 

ATTR_C0L(0) , 




P ANEL_I TEM_Y, 

ATTR_R0W(5) , 




PANEL DISPLAY LEVEL, 

PANEL CURRENT, 




PANEL_LABEL_STRING, 

"Recursively list subdirectories? ", 




PANEL_CH0ICE_STRINGS, 

"No", "Yes", 0, 




PANEL CLIENT DATA, 

" R ", 




o 





panel_create_item(ls_flags_panel. 

PANE L_CY CLE, 




PANEL_ITEM_X, 

ATTR_C0L(0), 




P ANEL_I TEM__Y, 

ATTR_R0W(6), 




PANEL DISPLAY LEVEL, 

PANEL_CURRENT, 




PANEL LABEL_STRING, 

"List '. f files? ", 




PANEL CHOICE STRINGS, 

"No", "Yes", 0, 




PANEL_CLIENT_DATA, 

l» a II 

a , 




o 





panel_create_item(ls_flags _panel. 

PANE L___CY CLE, 




PANEL_ITEM_X, 

ATTR__C0L (0) , 




PANEL_ITEM_Y, 

ATTR__R0W (6) , 




PANEL_D ISP LA Y_LEVEL, 

PANEL_CURRENT, 




PANEL_LABEL__STRING, 

"Indicate type of file? ", 




PANEL_CHOICE_STRINGS, 

"No", "Yes", 0, 




P ANEL_CLI ENT_D ATA, 

" F ", 




o 





done_item = panel_create_item(ls_ 

flags_panel, PANELJBUTTON, 




PANEL_ITEM_X, 

ATTR_COL(0), 




PANEL_ITEM_Y, 

ATTR_ROW(7), 




PANEL__LABEL_IMAGE, 

panel_button_image(panel, "Done", 0, 0), 




PANEL NOTIFY__PR0C, 

done_j?roc. 




0); 





window fit(ls_flags_panel); /* fit panel around its items */ 



} 

window fit(ls_flags_frame); /* fit frame around its panel */ 



char * 




compose_ls_options () 

/ 





static char flags[20]; 

char *ptr; 

char flag; 

int first__flag = TRUE; 





Panel__item item; 





char *client_data; 





int index; 



V_ 


ptr = flags; 
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panel_each_item(ls_flags _j?anel, item) 
if (item != done_item) { 

client_data = panel_get(item, PANEL_CLIENT_DATA, 0); 
index = (int)panel_get_value(item); 
flag = client_data[index]; 
if (flag !=''){ 

if (first__flag) { 

*ptr++ = 

first_flag = FALSE; 

} 

*ptr++ * flag; 

} 

} 

panel_end_each 
*ptr = 'Non¬ 
return flags; 

} 

void 

ls_proc () 

{ " 

static char previous_dir [MAX_PATH_LEN] ; 
char *current_dir; 

char cmdstring[100]; /* dir_item's value can be 80, plus flags */ 

current_dir = (char *) panel__get_value (dir_item); 

if (strcmp(current_dir, previous_dir)) { 

chdir ( (char *)panel_get_value (dir_item)) ; 
strcpy(previous_dir, current_dir); 

} 

sprintf(cmdstring, "Is %s %s/%s\n", 
compose_ls_options(), 
current_dir, 

panel_get_value(fname_item)); 
ttysw_input(ttysw, cmdstring, strlen(cmdstring)); 

} 

void 

ls_f lags_jproc () 

{ " 

window_set (ls_flags_frame, WIN_SHOW, TRUE, 0); 

} 

void 

done_proc () 

{ 

window_set (ls_flags_f rame, WIN_SHOW, FALSE, 0); 

} 

/* return a pointer to the current selection */ 
char * 

get_selection () 

{ 

static char filename[MAX_FILENAME_LEN]; 

Seln_holder holder; 

Seln__request ^buffer; 
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holder = seln_inquire(SELN_PRIMARY); 

buffer = seln_ask(&holder, SELN_REQ_CONTENTS_ASCII, 0, 0); 
strncpy( 

filename, buffer->data + sizeof(Seln_attribute), MAX_FILENAME_LEN); 
return(filename); 


} 


/* return 1 if file exists, else print error message and return 0 */ 
stat_file(filename) 
char *filename; 

{ 

static char previous_dir [MAX_PATH_LEN] ; 
char *current_dir; 
char this_file [MAX_PATH_LEN] ; 
struct stat statbuf; 

current_dir = (char *)panel_get_value(dir_item); 

if (strcmp(current_dir, previous_dir)) { 

chdir((char *)panel_get_value(dir_item)); 
strcpy(previous_dir, current_dir); 

} 

sprintf(this_file, "%s/%s", current_dir, filename); 
if (stat(this_file, fcstatbuf) < 0) { 

char buf[MAX_FILENAME_LEN+11]; /* big enough for message */ 

sprintf(buf , "%s not found.", this_file); 
msg(buf, 1); 
return 0; 

} 

return 1; 

} 

void 

edit_proc () 

{ 

void edit_f ile_proc () , edit_sel_proc () ; 

int file_mode = (int) panel_get__value (filing_mode_item) ; 

if (file_mode) { 

(void) edit_sel_proc () ; 

} else { 

(void) edit_f ilej>roc () ; 

} 

} 

void 

edit_f ile_proc () 

{ 

char *filename; 

/* return if no selection */ 

if (!strlen(filename = (char *)panel_get_value(fname_item))) { 

msg("Please enter a value for \"File:\".", 1); 
return; 

} 


/* return if file not found */ 
if (!stat_file(filename)) 
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return; 

window_set(editsw, TEXTSW_FILE, filename, 0); 

window_set(edit_frame, FRAME_LABEL, filename, WIN_SH0W, TRUE, 0); 

} 

void 

edit_sel_jproc () 

{ 

char *filename; 

/* return if no selection */ 
if (!strlen(filename = get_selection ())) { 

msg("Please select a file to edit.", 0); 
return; 

} 

/* return if file not found */ 
if (!stat_file(filename)) 
return; 

window_set(editsw, TEXTSW_FILE, filename, 0); 

window_set(edit_frame, FRAME_LABEL, filename, WIN_SH0W, TRUE, 0); 

} 

void 

del_proc() 

{ 

char buf[300]; 

char *filename; 
int result; 

Event event; /* unused */ 

int file_mode = (int) panel_get_value (filing_mode_item) ; 

/* return if no selection */ 
if (file_mode) { 

if (!strlen(filename = get_selection())) { 

msg("Please select a file to delete.", 1); 
return; 

} 

} else { 

if (!strlen(filename = (char *)panel_get_value(fname_item))) { 

msg("Please enter a file name to delete.", 1); 
return; 

} 

} 

/* return if file not found */ 
if (!stat_file(filename)) 
return; 

/* user must confirm the delete */ 
result = alert^prompt(base_frame, Sevent, 

ALERT_ME S SAGE_S TRINGS, 

"Ok to delete file:", 
filename. 
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0, 

ALERT_BUTTON_YES, "Confirm, delete file", 

ALERT_BUTTON_NO, "Cancel", 

0 ); 

switch (result) { 
case ALERT_YES: 

unlink(filename); 

sprintf(buf, "%s deleted.", filename); 

msg(buf, 0); 

break; 

case ALERT_N0: 
break; 

case ALERT_FAILED: /* not likely to happen unless out of FDs */ 
sprintf(buf, "Ok to delete file %s?", filename); 
result = confirm^yes(buf); 
if (result) { 

unlink(filename); 

sprintf(buf, "%s deleted.", filename); 
msg(buf, 1); 

} 

break; 

} 

} 

int 

confirm_quit() 

{ 

int result; 

Event event; /* unused */ 

char *msg = "Are you sure you want to Quit?"; 

result = alert_prompt(base_frame, Sevent, 

ALERT__ME S S AGE_S TRINGS, 

"Are you sure you want to Quit?", 

0, 

ALERT_BUTTON_YES, "Confirm", 

ALERT_BUTT0N_N0, "Cancel", 

0 ); 

switch (result) { 
case ALERT_YES: 
break; 

case ALERT_N0: 
return 0; 

case ALERT_FAILED: /* not likely to happen unless out of FDs */ 
result = confirm_yes(msg); 
if (!result) { 
return 0; 

} 

break; 

} 

return 1; 

} 

static Notify__value 
filer_destroy_func(client, status) 

Notify_client client; 

Destroy_status status; 

{ 
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if (status == DESTROY__CHECKING) { 

if (quit_confirmed_from_panel) { 

return(notify_next_destroy_func(client, status)); 

} else if (confirm_quit() == 0) { 

(void) notify_veto_destroy((Notify_client)(LINT_CAST(client))); 
return(NOTIFY_DONE); 

} 

} 

return(notify_next_destroy_func(client, status)); 

} 

void 

quit_jproc () 

{ 

if (confirm_quit()) { 

quit_confirmed_from_panel = 1; 
window_destroy (base__frame) ; 

} 

} 

msg(msg, beep) 
char *msg; 
int beep; 

{ 

char buf[300]; 

int result; 

Event event; /* unused */ 

char *contine_msg - "Press \"Continue\" to proceed."; 

result = alert_prompt(base_frame, fcevent, 

ALERT_MESSAGE__STRINGS, 
msg, 

contine_msg, 

0, 

ALERT_N0_BEEPING, (beep) ? 0:1, 

ALERT_BUTTON_YES, "Continue", 

ALERT_TRIGGER, ACTION_STOP, /* allow either YES or NO answer */ 

0 ); 

switch (result) { 
case ALERT_YES: 

case ALERT_TRIGGERED: /* result of ACTI0N__ST0P trigger */ 
break; 

case ALERT_FAILED: /* not likely to happen unless out of FDs */ 
sprintf(buf, "%s Press \"Continue\" to proceed.", msg); 
result = conf irm__ok (buf); 
break; 

} 

} 

/* confirmer routines to be used if alert fails for any reason */ 

static Frame init_confirmer(); 

static int confirm(); 

static void yes_no_ok (); 

int 

confirm__yes (message) 

char *message; 
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{ 

return confirm(message, FALSE); 

} 


int 

confirm_ok(message) 

char *message; 

{ 

return confirm(message, TRUE); 

} 


static int 

confirm (message, ok_only) 
char ^message; 

int ok_only; 

{ 

Frame confirmer; 

int answer; 


/* create the confirmer */ 

confirmer = init_confirmer(message, ok_only); 

/* make the user answer */ 

answer = (int) window_loop(confirmer); 

/* destroy the confirmer */ 

window_set (confirmer, FRAME__N0_C0NFIRM, TRUE, 0); 
window_destroy(confirmer); 
return answer; 


static Frame 

init_confirmer(message, ok_only) 
char ^message; 

int ok_only; 

{ 


Frame 

Panel 

Panel__item 

int 

Rect 

struct pixrect 


confirmer; 

panel; 

message_item; 
left, top, width 
*r; 

*pr; 


height; 


confirmer = window_create(0, FRAME, FRAME_SHOW_LABEL, FALSE, 0); 
panel = window_create(confirmer, PANEL, 0); 

message_item = panel_create_item(panel, PANEL_MESSAGE, 

PANEL_LABEL_STRING, message, 0); 


if (ok_only) { 

pr = panel_button__image (panel, "Continue", 8, 0) ; 
width = pr->pr_width; 

} else { 

pr = panel_button_image(panel, "Cancel", 8, 0); 
width - 2 * pr->pr_width + 10; 

} 


/* center the yes/no or ok buttons under the message */ 
r = (Rect *) panel_get (message__item, PANEL_ITEM_RECT); 
left = (r->r_width - width) / 2; 
if (left < 0) 


m sun 

\r microsystems 


Revision A, of May 9, 1988 





400 SunView 1 Programmer’s Guide 


left = 0; 

top = rect_bottom(r) + 5; 


if (ok__only) { 

panel_create_item (panel , PANEL_BUTTON f 

P ANEL__ITEM_X, left, PANEL_ITEM_Y, top, 

P ANEL_LABEL_IMAGE, pr, 

PANEL_CLIENT_DATA, 1, 

PANEL_NOTIFY_PROC, yes_no_ok, 

0 ); 

} else { 

panel_create_item (panel, PANEL_BUTTON, 

PANEL_ITEM_X, left, PANEL_ITEM_Y, top, 

PANEL_LABEL_IMAGE, pr, 

P ANEL_CL I ENT_D AT A, 0, 

P ANEL_NOTIFY__PROC, yes_no__ok, 

0 ); 

panel__create_item (panel, PANEL__BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, "Confirm", 8, 0) , 
P ANEL_CL I ENT_DAT A, 1, 

PANEL_NOTIFY__PROC, yes_no__ok, 

0 ); 

} 


window_fit (panel) ; 
window_fit(confirmer); 


/* center the confirmer frame on the screen */ 


r 

width 

height 

left 

top 

if (left < 
left = 
if (top < 
top = 


: 0 ) 
• 0 ; 
0 ) 
0 ; 


(Rect *) window__get(confirmer, WIN_SCREEN_RECT); 
(int) window_get(confirmer, WIN_WIDTH); 

(int) window_get(confirmer, WIN_HEIGHT); 
(r->r__width - width) / 2; 

(r->r_height - height) / 2; 


window set(confirmer, WIN X, left, WIN_Y, top, 0); 


return confirmer; 

} 


static void 
yes_no__ok (item, event) 

Panel_item item; 

Event *event; 

{ 

window__return (panel_get (item, PANEL_CLIENT_DATA) ) ; 

} 
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A.2. image_browser_1 The following program is discussed in Chapter 4, Using Windows. It lets the 

user browse through icons and display them. It shows a more complex subwin¬ 
dow layout. 
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/***************************************************************************/ 
/* image_browser_l.c */ 

/***************************************************************************/ 

#include <suntool/sunview,h> 

♦include <suntool/panel.h> 

♦include <suntool/tty.h> 

♦include <stdio.h> 

♦include <suntool/icon_load.h> 

♦include <suntool/seln.h> 

Frame frame; 

Panel control_panel, display_panel; 

Tty tty; 

Panel__item dir_item, fname__item, image_item; 

ls^proc(), show_proc(), quit_proc(); 

char *get_selection (); 

♦define MAX_PATH_LEN 1024 
♦define MAX_FILENAME_LEN 256 

main(argc f argv) 
int argc; 
char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABE L, "image_browser_l”, 

0 ); 

init__tty (); 
init__control_panel () ; 
init_display_panel () ; 
window_fit (frame) ; 
window__main_loop (frame) ; 
exit (0); 

} 

init_tty () 

{ 

tty = window_create(frame, TTY, 

WIN__COLUMNS, 30, 

WIN_ROWS, 20, 

0 ); 

} 
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init_control_panel() 

{ 

char *getwd(); 

char current dir[1024]; 


control_panel = window_create(frame, PANEL, 0); 

dir item “= panel_create_item(control_panel, PANEL_TEXT, 

_ PANEL_VALUE_DISPLAY_LENGTH, 13, 

PANEL_LABEL_STRING, "Dir: ", 

PANEL_VALUE, getwd(current_dir), 

0 ); 


fname_item - panel_create_item(control_panel, PANEL_TEXT, 
PANEL_ITEM_X, ATTR_C0L(0), 

PANEL_ITEM_Y, ATTR_ROW(1), 

PANEL_VALUE_DISPLAY_LENGTH, 13, 

PANEL_LABEL_STRING, "File:", 

0 ); 


panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_ITEM_X, ATTR_C0L(0) , 

PANEL_ITEM_Y, ATTR_ROW(2), 

PANEL_LABEL_IMAGE, panel_button_image(control_panel,"List" 
PANEL_NOTIFY_PROC, ls_proc, 

0 ); 


0 , 0 ), 

/ 


panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(control_panel,"Show”,0,0), 
PANEL_NOTIFY_PROC, show_proc, 

0 ); 


panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(control_panel,"Quit",0,0), 
PANEL_N OTIFY_PR0C, quit_proc, 

0 ); 


window_fit(control_panel); 

} 
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ls_proc() 

{ " 

static char previous_dir[MAX_PATH_LEN]; 
char *current_dir; 
char cmdstring[100]; 

current_dir = (char *) panel_get__value (dir_item) ; 

if (strcmp(current_dir, previous_dir)) { 
chdir(current_dir); 

sprintf(cmdstring, "cd %s\n", current_dir) ; 
ttysw_input(tty, cmdstring, strlen(cmdstring)); 
strcpy(previous_dir, current_dir); 

} 

sprintf(cmdstring, "Is -1 %s\n", panel_get_value (fname_item) ) ; 
ttysw_input(tty, cmdstring, strlen(cmdstring)); 

} 

quit_proc() 

{ 

window_destroy(frame); 

} 

show_jproc () 

{ 

char *filename; 

if (!strlen(filename = get_selection ())) 
return; 

load__image (filename) ; 

} 

load_image(filename) 
char *filename; 

{ 

Pixrect *image; 

char error_msg [ IL_ERRORMSG_SIZE ] ; 

if (image = icon_load_mpr(filename, error_msg)) { 
panel_set(image_item, 

PANE L_ITEM_X, ATTR_COL(5), 

PANEL_I TEM__Y, ATTR_ROW (4) , 

PANEL_LABEL_IMAGE, image, 

0 ); 

} 

} 
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init_display_panel () 


display_panel * window_create(frame, PANEL, 


WIN__BELOW, control_panel, 
WIN_RIGHT_OF, tty, 

0 ); 


image_item = panel_create_item(display_panel, PANEL_MESSAGE, 0); 

} 

char * 

get_selection () 

{ 

static char filename[MAX_FILENAME_LEN]; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire(SELN_PRIMARY); 

buffer = seln_ask(^holder, SELNJREQ_CONTENTS_ASCII, 0, 0); 

strncpy(filename, buffer->data + sizeof(Seln_attribute), MAX_FILENAME__LEN) ; 
return (filename); 


J 
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A.3. image_browser_2 The following program is discussed in Chapter 4, Using Windows. It is a more 

complex icon browser than the previous example It illustrate how you can use 
row!column space to specify the size of a subwindow. 
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/***************************************************************************/ 
♦ifndef lint 

static char sccsid[] = M @(#)image_browser_2.c 1.3 86/09/15 Copyr 1986 Sun Micro"; 
#endif 

/***************************************************************************/ 

♦include <suntool/sunview.h> 

♦include <suntool/panel.h> 

♦include <suntool/tty.h> 

♦include <stdio.h> 

♦include <suntool/icon_load.h> 

♦include <suntool/seln.h> 

♦include <suntool/expand_name.h> 

♦include <suntool/scrollbar.h> 

static char namebuf[100]; 

static int file_count, image_count; 

static struct namelist *name_list; 

♦define get_name(i) name_list->names[(i)] 

Frame frame; 

Panel control_panel, display_panel; 

Tty tty; 

Panel_item dir_item, fname_item, image__item; 

show_jproc () , browsej)roc () , quit_proc () ; 

Pixrect *get_image () ; 

char *get_selection(); 

♦define MAX_PATH_LEN 1024 
♦define MAX_FILENAME_LEN 256 

main(argc f argv) 
int argc; 
char **argv; 

{ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

FRAME_LABEL, "image_browser_2", 

0 ); 

init__control_panel () ; 
init_display_j>anel (); 
window_set (control_panel, 

WIN_WIDTH, window_get(display_panel, WIN_WIDTH, 0), 

0 ); 

window_fit (frame) ; 
window_main__loop (frame) ; 
exit(0); 

} 
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init__control__panel () 

{ 

char current_dir [MAX_PATH__LEN] ; 

control_panel = window_create(frame, PANEL, 0); 

dir_item = panel__create_item(control__panel, PANEL_TEXT, 

PANEL_LABEL__X, ATTR_COL (0) , 

PANEL_LABEL_Y, ATTR_ROW (0) , 

PANEL_VALUE_DISPLAY_LENGTH, 23, 

PANEL__VALUE, getwd (current_dir) , 

PANEL_LABEL__STRING, "Dir: " , 

0); 

(void) panel_create_item(control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(control_panel,"Browse",0,0), 
PANEL_NOTIFY_PROC, browse_proc, 

0); 

fname__item = panel_create_item (control_j?anel, PANEL_TEXT, 

PANEL_LABEL_X, ATTR_COL (0) , 

PANEL_LABEL__Y, ATTR_ROW (1) , 

PANEL_VALUE_DI SPLAY_LENGTH, 23, 

PANEL_LABE L_STRING, "File:", 

0); 

(void) panel__create__item (control_panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (control_panel, "Quit", 6,0) , 
PANEL_NOTIFY_PROC, quit_proc, 

0); 

window_fit_height (control_panel); 

window_set(control_panel, PANEL_CARET_ITEM, fname_item, 0); 
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browse^proc() 

{ 

Panel_item olcMLtem; 
register int i; 
int len; 

Pixrect *image; 

int previous_image_count; 

register int row, col; 

set_directory(); 
match_files() ; 

panel__each_item (display_panel, old__item) 

pr_destroy ((Pixrect *) panel_get (old_item, PANEL_LABEL__IMAGE) ) ; 
panel_f ree (old__item) ; 
panel_end_each 

previous__image__count = image_count; 

for (row = 0 f image__count = 0; image__count < file_count; row++) 
for (col = 0; col < 4 && image_count < file_count; col++) { 
if (image = get_image(image_count)) { 

panel_create_item (display_panel f PANEL__MESSAGE, 

PANEL__ITEM_Y f ATTR_ROW (row) f 

PANEL_ITEM_X f ATTR_C0L (col) , 

PANEL_LABEL_IMAGE, image, 0); 

image_count++; 

} 

} 

if (image_count <=* previous_image__count) 

panel_update__scrolling_size (display_panel) ; 

panel_paint(display_panel, PANEL_CLEAR); 

free_namelist (name__list); 

} 

set_directory() 

{ 

static char previous_dir[MAX_PATH_LEN]; 
char *current__dir; 

current_dir = (char *) panel_get_value (dir_item) ; 

if (strcmp(current_dir, previous_dir)) { 

chdir(current_dir); 

strcpy(previous_dir, current_dir); 

} 


Pixrect * 
get_image(i) 
int i; 

{ 

char error_msg[IL_ERRORMSG_SIZE]; 

return (icon_load_mpr(get_name(i), error_msg)); 

} 
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match_files () 

{ 

char *val; 

val = (char *)panel_get_value(fname_item); 
strcpy(namebuf, val); 
name_list = expand_name(namebuf); 
file_count = name_list->count; 


quit_proc() 

{ 

window_destroy(frame); 

} 

show_j?roc () 

{ 

char *filename; 

if (!strlen(filename = get_selection ())) 
return; 

load_image(filename); 

} 

load_image(filename) 
char *filename; 

{ 

Pixrect *image; 

char error_msg[IL_ERRORMSG_SIZE]; 

if (image = icon_load_mpr(filename, error_msg)) { 
panel_set(image__item, 

PANEL_ITEM_X, ATTR_COL(5) f 

PANE L_ITEM_Y f ATTR_R0W(4) f 

PANEL_LABEL_IMAGE, image, 

0 ); 

} 

} 
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init_display_panel () 

{ 

int width; 

Scrollbar sb = scrollbar_create(SCROLL__MARGIN,10,0); 
width = (int) scrollbar__get (sb, SCR0LL_THICKNESS, 0); 
display_panel = window_create(frame, PANEL, 


WIN_BEL0W, 

WIN_X, 

WIN_VERTICAL_SCROLLBAR, 
WIN_ROW_HEIGHT, 

WI N__COLUMN_WI DTH, 
WIN_ROW_GAP, 

WIN_COLUMN_GAP, 

WIN_LEFT_MARGIN, 

WI N__TOP__MARGIN, 

WIN_R0WS, 

WI N__C0LUMN S, 

0 ); 

window__set (display__panel, WIN__LEFT__MARGIN, 


control_panel, 
0 , 
sb, 

64, 

64, 

10 , 

10 , 

width + 10, 

10 , 

4, 

4, 


10 , 0 ); 


char * 

get_selection() 

{ 

static char filename [MAX__FILENAME_LEN]; 

Seln_holder holder; 

Seln_request *buffer; 

holder = seln_inquire(SELN_PRIMARY); 

buffer = seln__ask (&holder, SELN__REQ_CONTENTS_ASCI1, 0, 0); 

strncpy(filename, buffer->data + sizeof (Seln_attribute), MAX_FILENAME_LEN); 
return (filename); 

} 
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A.4. tty Jo The following program demonstrates the use of ttysw_input (), 

ttysw_output () and TTY escape sequences. These functions are explained 
in Chapter 11, TTY Subwindows. 

tty Jo creates a panel and a tty subwindow. You can send arbitrary character 
sequences to the latter as input or output by manipulating panel items. There is 
also a button that sends the current time within the escape sequence to set the 
frame label. Try sending different sequences to the tty subwindow. Press 
CTRL-R to see the difference between what appears on the screen and what was 
input to the pseudo-tty. Also try starting the tool with a program such as vi as a 
command line argument. 
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/*****************************************************************************/ 
#ifndef lint 

static char sccsid[] = (#)tty_io.c 1.4 87/11/19 Copyr 1986 Sun Micro"; 

#endif 

/*****************************************************************************/ 

#include <stdio.h> 

#include <suntool/sunview.h> 

#include <suntool/tty.h> 

#include <suntool/panel.h> 

#define TEXT ITEM MAX LENGTH 25 

Tty 

Panel_item 
char 

static void 
static void 
static void 

main(argc, argv) 


int 

argc; 

char 

**argv; 

Frame 

frame; 

Panel 

panel; 


frame * window_create(NULL, FRAME, 

FRAME_ARGS, 

WIN_ERROR_MSG, 

0 ); 

panel = window__c reate (frame, PANEL, 0) ; 

/* set up a simple panel subwindow */ 

panel_create_itern(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Input text", 11, 0), 
PANEL_NOTIFY_PROC, input_text, 

0 ); 

panel__create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Output text", 11, 0), 
PANEL_NOTIFY_PROC, output_text, 

0 ); 

text_item = panel__create_item (panel, PANEL_TEXT, 

PANEL_LABEL_STRING, "Text:", 

PANEL_VALUE, "Hello hello", 

PANE L_VALUE_D ISP LAY_LENGTH, TEXT_I TEM_MAX_LENGTH, 

0 ); 

panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL__IMAGE, panel_button__image (panel, "Show time", 11, 0), 
PANEL_NOTIFY_PROC, output_time, 

0 ); 

window_fit_height (panel) ; 


argc, argv, 

"Can't create tool frame". 


tty; 

text_item; 
tmp_buf[80] ; 

input_text() ; 
output_text () ; 
output_time () ; 


m sun 

Xr microsystems 


Revision A, of May 9, 1988 





414 SunView 1 Programmer’s Guide 


/* Assume rest of arguments are for tty subwindow, except FRAME_ARGS leaves the 
* program_name as argv[0], and we don't want to pass this to the tty subwindow. 
*/ 

argv++; 

tty = window_create(frame, TTY, 

TTY_ARGV, argv, 

WIN_ROWS, 24, 

WIN_COLUMNS, 80, 

0 ); 

window_fit (frame) ; 

ttysw_input(tty, "echo my pseudo-tty is 'tty'\n H , 28); 

window_main_loop (frame); 
exit(0); 

} 

static void 

input_text (item, event) 

Panel__item item; 

Event *event; 

{ 

strcpy (tmp__buf, (char *) panel_get_value (text_itern) ) ; 
ttysw_input(tty, tmp_buf, strlen(tmp_buf)); 

} 

static void 

output__text (item, event) 

Panel_item item; 

Event *event; 

{ 

strcpy (tmp__buf, (char *) panel__get_value (text_item) ) ; 
ttysw_output(tty, tmp_buf, strlen(tmp_buf)); 

} 
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static void 

output__time (item, event) 


Panel item item; 


Event 


*event; 


#include <sys/time.h> 

#define ASCTIMELEN 26 


struct timeval tp; 


/* construct escape sequence to set frame label */ 
tmp_buf[0] = '\033'; 
tmp_buf[1] = ']'; 
tmp__buf [2 ] = ' 1' ; 

tmp_buf[2 + ASCTIMELEN + 1] = f \033'; 
tmp_buf [2 + ASCTIMELEN + 2] - '\V; 
gettimeofday(&tp, NULL); 

strncpy(&tmp_buf[3], ctime(&tp.tv_sec) f ASCTIMELEN); 
ttysw___output (tty, tmp_buf, ASCTIMELEN + 5); 


J 
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A.5. fontjnenu The next program, fontjnenu , builds on several of the examples given in Chapter 

12, Menus. Examples of the font menu it creates are shown below: 


Frame 

*ll 



Family 

Courier 


■ 

Size 

Serif 



Bold 

— 


L 

Italic 


8 | 

ffl? 

CUR 

10 


~ ~— 

12 


Screen 

14 



16 g 



18 1 


Frame 
Family 

=*> |g 
=3> | 

Size 

8 

Bold 

18 

Italic 

12 


14 


16 


18 
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/*****************************************************************************/ 

#ifndef lint 

static char sccsid[] * M @(#)font_menu.c 1.2 86/09/15 Copyr 1986 Sun Micro"; 

#endif 

/*****************************************************************************/ 

#include <suntool/sunview.h> 

♦include <suntool/panel.h> 

♦include <suntool/walkmenu.h> 

void set_family () f set_size () , set_on_off () , toggle_on__of f () , open_fonts (); 

Menu new_menu (), initialize_on_off (); 
char *int_to_str(); 
extern char * sprintf(); 
extern char * malloc(); 

Panel_item feedback_item; 

char *family, *size, *bold, ^italic; 

Pixfont *cour, *serif, *apl, *cmr, ^screen; 

/*****************************************************************************/ 

/* main */ 

/* First create the base frame, the feedback panel and feedback item. The */ 

/* feedback item is initialized to "gallant 8". */ 

/* Then get the frame's menu, call new_menu() to create a new menu with the */ 

/* original frame menu as a pullright, and give the new menu to the frame. */ 

/*****************************************************************************/ 

main(argc, argv) 
int argc; 
char *argv[]; 

{ 

Frame frame; 

Panel panel; 

Menu menu; 
int defaults; 

frame = window_create(NULL, FRAME, FRAME_LABEL, "Menu Test — Try frame menu.", 0); 
panel = window_create(frame, PANEL, WIN_R0WS, 1, 0); 

feedback_item = panel_create_item(panel, PANEL_MESSAGE, PANEL_LABEL_STRING, "", 0) ; 

family = "Gallant", size = "8", bold - italic = ""; 
update_feedback(); 

/* remember if user gave -d flag */ 

if (argc >= 2) defaults = strcmp(argv[1], "-d") == 0; 

menu = (Menu)window_get(frame, WIN_MENU); 
menu = new_menu(menu, defaults); 
window_set(frame, WIN_MENU, menu, 0); 

window_main__loop (frame) ; 

} 
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/*****************************************************************************/ 
/* new_menu — returns a new menu with 'original menu' as a pullright. */ 

/*****************************************************************************/ 

Menu 

new_menu(original_menu f defaults) 

Menu original_menu; 
int defaults; 

{ 

Menu new_menu, family__menu, size_menu, on_off_menu; 
int i; 


/* create the on-off menu, which will be used as a pullright 
* for both the bold and italic items to the new menu. 

*/ 

on_off_menu = menu_create(MENU_STRING_ITEM, "On", 1, 

MENU_STRING_ITEM, "Off", 0, 

MENU_GEN_P ROC, initialize_on_off, 

MENU_NOTIFY_PROC, set_on_off, 

0 ); " 

/* create the new menu which will eventually be returned */ 


open_fonts(); /* first open the needed fonts */ 
new_menu = menu_create( 

MENU_P ULLRIGHT_ITEM, 

"Frame”, 


or iginal__menu, 
MENU_P ULLRIGHT_ITEM, 
"Family", 


family_menu = menu_create ( 


MENU_ITEM, 

MENU_STRING, 

MENU_F0NT, 

0 , 

MENU_ITEM, 

MENU_STRING, 

MENU_F0NT, 

0 , 

MENUJETEM, 

MENU__STRING, 

MENU_F0NT, 

0 , 

MENU_ITEM, 

MENU_STRING, 

MENU_F0NT, 

0 , 


"Courier", 

cour. 


"Serif", 

serif. 


"aplAPLGIJ" 
apl. 


"CMR", 
cmr. 
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MENU_ITEM, 

MENU_STRING, "Screen", 

MENU_FONT, screen, 

0, 

MENU_N0TIFY_PROC, set_family, 

0 ), 

MENU_P ULLRI GHT_I TEM, 

"Size", size_menu = menu__create (0) , 

MENU_ITEM, 

MENU_STRING, "Bold", 

MENU_PULLRIGHT, on_off_menu, 

MENU_NOTIFY_PROC, toggle_on_off, 

MENU_CLIENT_DATA, &bold, 

0, 

MENU_ITEM, 

MENU__STRING, "Italic", 

MENU_P ULLRIGHT, on_off_menu, 

MENU_NOTIFY_PROC, toggle_on_off, 

MENU_CLIENT_DATA, Sitalic, 

0, 

0); 

/* give each item in the family menu the size menu as a pullright */ 
for (i = (int)menu_get(family_menu, MENU_NITEMS); i > 0; —i) 
menu_set (menu__get (family_menu, MENU_NTH_ITEM, i) , 

MENU_PULLRIGHT, size_menu, 0) ; 

/* put non-selectable lines inbetween groups of items in family menu */ 
menu__s et (f amily__menu, 

MENU_INSERT, 2, menu__create_item (MENU_STRING, "-", 

MENU__I NACTIVE, TRUE, 

0), 

0); 

menu_set (family_menu, 

MENU_INSERT, 5, menu_get (family___menu, MENU_NTH_ITEM, 3), 

0); " 

/* The size menu was created with no items. Now give it items representing */ 
/* the point sizes 8, 10, 12, 14, 16, and 18. */ 

for (i = 8; i <= 18; i += 2) 

menu_set(size_menu, MENU_STRING_ITEM, int_to_str(i), i, 0); 

/* give the size menu a notify proc to update the feedback */ 
menu_set (size_menu, MENU_NOTIFY_PROC, set_size, 0); 
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/* if the user did not give the -d flag, make all the menus come 

* up with the initial and default selections the last selected 

* item, and the initial selection selected. 

*/ 

if (!defaults) { 

menu_set(new_menu, 

MENU_DEFAULT_SELECTION, MENU_SELECTED, 

MENU_INITIAL_SELECTION, MENU_SELECTED, 
MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ); “ 

menu_set (family_menu, 

MENU_DEFAULT_SELECTION, MENU_SELECTED, 

MENU_INITIAL_SELECTION, MENU_SELECTED, 

MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ); " 

menu_set (size_menu, 

MENU_DEFAULT_SELECTION, MENU_SELECTED, 

MENU_INITIAL_SELECTION, MENU_SELECTED, 

MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ); “ 

menu__set (on_off_menu, 

MENU__DEF AULT_SELECT I ON, MENU_SELECTED, 
MENU_INITIAL_SELECTION, MENU_SELECTED, 
MENU_INITIAL_SELECTION_SELECTED, TRUE, 

0 ); ‘ 


return (new_menu); 

} 
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/*****************************************************************************/ 


/* set_family — notify proc for family menu. Get the current family and */ 
/* display it in the feedback panel. Note that we first get the value */ 
/* of the menu item. This has the side effect of causing any pullrights */ 
/* further to the right of mi to be evaluated. Specifically, the value of */ 
/* each family item is the value of its pullright — namely the size menu. */ 
/* When the size menu is evaluated, the notify proc set_size() is called, */ 
/* which updates the feedback for the size. */ 


/*****************************************************************************/ 

/*ARGSUSED*/ 

void 

set_family (m, mi) 

Menu m; 

Menu_item mi; 

{ 

menu_get(mi, MENU_VALUE); /* force pullrights to be evaluated */ 

family = menu_get(mi, MENU_STRING); 
update_feedback(); 

} 

/****************************************************************************V 
/* set_size — notify proc for the size menu. */ 

/*****************************************************************************/ 

/*ARGSUSED */ 
void 

set_size(m, mi) 

Menu m; 

Menu_item mi; 

{ 

size = menu_get(mi, MENU_STRING) ; 
update_feedback(); 

} 
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/****************************************************************************/ 


/* initialize_on_off — generate proc for the on_off menu. */ 
/* The on-off menu is a pullright of both the bold and the italic menus. */ 
/* We want it to toggle — if its parent was on, it should come up with */ 
/* "Off" selected, and vice-versa. We can do that by first getting the */ 
/* parent menu item, then, indirectly through its client data attribute, */ 
/* seeing if the string representing the bold or italic state is null. */ 
/* If the string was null, we set the first item ("On") to be selected, */ 
/* else we set the second item ("Off") to be selected. */ 


/*****************************************************************************/ 

Menu 

initialize_on_off(m, op) 

Menu m; Menu_generate op; 

{ 

Menu_item parent__mi; 
char **name; 


if (op != MENU_CREATE) return (m); 

parent_mi = (Menu__item) menu_get (m, MENU_PARENT) ; 
name = (char * *) menu_get (parent_mi, MENU_CLIENT_DATA); 

if (**name == NULL) 


menu_set (m. 

D 

i 

_SELECTED, 

i. 

0); 

menu_set (m. 

MENU_ 

SELECTED, 

2, 

0); 


return (m); 
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/*****************************************************************************/ 


/* set_on_off — notify proc for on-off menu. */ 
/* Set the feedback string — italic or bold — appropriately depending on */ 
/* the current setting. Note that the "On" item was created to return a */ 
/* value of 1, and the "Off" item will return a value of 0. */ 


/*****************************************************************************/ 

void 

set_on_off (m, mi) 

Menu m; Menu_item mi; 

{ 

Menu_item parent_mi; 
char **name; 

parent_mi = (Menu_item) menu_get (m, MENU_PARENT) ; 
name = (char **)menu_get(parent__mi, MENU_CLIENT_DATA); 
if (menu_get(mi, MENU_VALUE)) 

*name = (char *)menu_get(parent_mi, MENU_STRING); 

else 

*name * ""; 
update_feedback(); 

} 

/*****************************************************************************/ 
/* toggle_on_off — notify proc for the "Bold" and "Italic" menu items. */ 

/* Using a notify proc for the menu item allows toggling without bringing */ 

/* up the on-off pullright. */ 

/*****************************************************************************/ 

/*ARGSUSED*/ 

void 

toggle_on_off(m, mi) 

Menu m; 

Menu_item mi; 

{ 

char **name; 

name = (char **) menu_get (mi, MENU_CLIENT_DATA); 
if (**name -= NULL) 

*name = (char *)menu_get(mi f MENU_STRING); 

else 

*name = ""•; 
update_feedback(); 

} 
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r 


update_feedback() 

{ 

char buf[30]; 

sprintf(buf, "%s %s %s %s", bold, italic, family, size); 
panel_set(feedback_item, PANEL_LABEL_STRING, buf, 0); 


char * 

int_jto_str (n) 

{ 

char *r = malloc(4); 
sprintf(r, "%d", n); 
return (r); 


void 

open_fonts () 

{ 

cour = pf_open("/usr/lib/fonts/fixedwidthfonts/cour.r.10"); 
serif = pf_open("/usr/lib/fonts/fixedwidthfonts/serif.r.10"); 
apl = pf_open("/usr/lib/fonts/fixedwidthfonts/apl.r.10"); 
cmr = pf_open("/usr/lib/fonts/fixedwidthfonts/cmr.b.8"); 
screen - pf__open ("/usr/lib/fonts/fixedwidthfonts/screen, r. 11") ; 

} 
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A.6. resize demo This program demonstrates how to resize the subwindows of a frame yourself if 

you need to use a complicated topology. 

The particular subwindow layout used here has four subwindows. One has a 
fixed width and height in pixels, another has a fixed width in characters (using 
the user-set default font), and the other two fill up the empty space. One of the 
subwindows also has a scrollbar. 

This program interposes in front of the frame’s client event handler. If the event 
is WIN_RESIZE, the program’s own resize () procedure is called, which sets 
the subwindow positions explicitly. 

For a discussion of interposing and the Notifier, see Chapter 17, The Notifier. 

The simpler case of using window attributes to layout subwindows is described 
under Explicit Subwindow Layout in Chapter @NumberOf(window), 
@TitleOf(window). 
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/★★★★a**********************************************************************/ 
#ifndef lint 

static char sccsid[] = "%Z%%M% %I% %E% Copyr 1986 Sun Micro"; 

#endif 

/★★a************************************************************************/ 

#include <suntool/sunview.h> 
tinclude <suntool/canvas.h> 

#include <suntool/scrollbar.h> 


Canvas Canvas_l, Canvas_2, Canvas_3, Canvas_4; 
Pixwin *Pixwin_l, *Pixwin__2, *Pixwin_3, *Pixwin_4; 
Rect framerect; 

PIXFONT *font; 


extern char * sprintf (); 
/* 

* font macros: 

* font_offset(font) 


★ 

★ 

* 

* 


■k 

*/ 


font_height (font) 


gives the vertical distance between 
the font origin and the top left corner 
of the bounding box of the string displayed 
(see Text Facilities for Pixrects in the 
Pixrect Reference Manual) 
gives the height of the font 


#define font__offset(font) (-font->pf_char['n f ].pc_home.y) 

#define font_height(font) (font->pf__defaultsize.y) 

/* 

* SunView-dependent size definitions 
*/ 

#define LEFT_MARGIN 5 

#define RIGHT_MARGIN 5 

#define BOTTOM_MARGIN 5 

#define SUBWINDOW_SPACING 

subwindows */ 


/* margin on left side of frame * 

/* margin on right side of frame */ 
/* margin on bottom of frame */ 

5 /* space in between adjacent 


/* 

* application-dependent size definitions 
*/ 

tdefine CANVAS_1_WIDTH 320 /* width in pixels of canvas 1 */ 

#define CANVAS_1_HEIGHT 160 /* height in pixels of canvas 1 */ 

fdefine CANVAS 3 COLUMNS 30 /* width in characters of canvas 3 */ 


main (argc, argv) 
int argc; 
char **argv; 

{ 

Frame frame; 

static Notify_value catch_resize(); 

static void draw_canvas_l () f draw_canvas_3 (); 

/* 

* create the frame and subwindows, and open the font 
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} 


* no size attributes are given yet 
*/ 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, argc, argv, 

WIN_ERROR_MSG, "Can't create tool frame", 

FRAME_LABEL, "Resize Demo", 

0 ) ; 

Canvas_l = window_create(frame, CANVAS, 

CANVAS_RESI ZE_PR0C, draw_canvas_l, 

0 ); 

Canvas_2 = window_create (frame, CANVAS, 

0 ); 

Canvas_3 = window_create(frame, CANVAS, 

WIN_JVERTICAL__SCROLLBAR, scrollbar_create ( 

SCROLL_P LACEMENT, SCROLL_EAST, 

0 ), 

CANVAS_RESIZE_PROC, draw_canvas_3, 

0 ); 

Canvas_4 = window_create(frame, CANVAS, 

0 ); 

Pixwin_l = canvas_j?ixwin (Canvas_l) ; 

Pixwin_2 = canvas_pixwin(Canvas_2); 

Pixwin_3 = canvas_pixwin (Canvas__3) ; 

Pixwin__4 = canvas_j?ixwin (Canvas_4) ; 
font = pf__default () ; 

/* 

* now that the frame and font sizes are known, set the initial 

* subwindow sizes 
*/ 

resize (frame) ; 

/* 

* insert an interposer so that whenever the window changes 

* size we will know about it and handle it ourselves 
*/ 

(void) not if y_interpose_event_func (frame, catch__resize, NOTIFY__SAFE) ; 


* start execution 
*/ 

window_main_loop (frame) ; 
exit (0); 


/* 

* catch_resize 

* 


interposed function which checks all input events passed to the frame 
for resize events; if it finds one, resize () is called to refit 
the subwindows; checking is done AFTER the frame processes the 
event because if the frame changes its size due to this event (because 
the window has been opened or closed for instance) we want to fit 
the subwindows to the new size 
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*/ 

static Notify_value 

catch_resize(frame, event, arg, type) 

Frame frame; 

Event *event; 

Notify_arg arg; 

Notify__event_type type; 

{ 

Notify_value value; 

value = notify_next_event__func(frame, event, arg, type); 
if (event_action(event) == WIN_RESIZE) 
resize(frame); 
return (value); 

} 

/* 

* resize 

* 

* fit the subwindows of the frame to its new size 
*/ 


resize(frame) 

Frame frame; 

{ 

Rect *r; 

int canvas_3__width; /* the width in pixels of canvas 3 */ 

int stripeheight; /* the height of the frame's name stripe */ 

/* if the window is iconic, don't do anything */ 


if ((int)window_get(frame, FRAME_CLOSED)) 
return; 

/* find out our new size parameters */ 

r = (Rect *) window_get (frame, WIN__RECT) ; 
framerect = *r; 

stripeheight = (int) window_get(frame, WIN_TOP_MARGIN) ; 


canvas_3_width = CANVAS_3_C0LUMNS * font->pf_defau It size .x 
+ (int) scrollbar_get(SCROLLBAR, SCROLL_THICKNESS); 


window_set(Canvas_2, 
WIN_X, 

WIN_Y, 

WIN_WIDTH, 


WIN HEIGHT, 


0 , 

0 , 

framerect. r__width - canvas_3_width 

- LEFT_MARGIN - SUBWINDOW_SPACING 

- RIGHT_MARGIN, 

framerect. r__height - CANVAS_1_HEIGHT 

- stripeheight - SUBWINDOW_SPACING - 
B0TT0M_MARGIN, 


0 ); 

window_set(Canvas_l, 

WIN_X, 0, 

WIN_Y, framerect .r__height - CANVAS_1_HEIGHT - 

SUBWINDOW_SPACING - stripeheight, 

WIN WIDTH, CANVAS_1_WIDTH, 
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WIN_HEIGHT, 

0 ); 

window_set(Canvas_4, 
WIN_X, 

WIN_Y, 

WIN_WIDTH, 


WIN_HEIGHT, 

0 ); 

window_set (Canvas_3, 
WIN_X, 

WIN_Y, 

WIN_WIDTH, 

WIN_HEIGHT, 


CANVAS_1_HEIGHT, 


CANVAS__1__WI DTH + SUBWINDOW_SPACING, 
framerect. r_height - CANVAS_1_HEIGHT 

- SUBWI NDOW_SP ACING - stripeheight, 
framerect. r_width - canvas_3_width 

- CANVAS_1_WIDTH - LEFT_MARGIN 

- 2 * SUBWINDOW_SPACING - RIGHT_MARGIN, 
C AN VA S_ 1_HE IGHT f 


framerect. r_width - canvas_3_width 

- LEFT_MARGIN - SUBWINDOW_SPACING, 

0 , 

canvas_3_width, 

framerect . r__height - stripeheight 

- B0TT0M_MARGIN, 


/* 

* draw_canvas_l 

* draw_canvas_3 

* 

* draw simple messages in the canvases 
*/ 


static void 
draw_canvas_l() 

{ 

char buf[64]; 


} 


sprintf(buf, "%d by %d pixels", 

CANVAS_1_WIDTH, CANVAS_1_HEIGHT); 
pw_text(Pixwin_l, 5, font_offset (font), PIX_SRC, font, 

"This subwindow is always "); 

pw_text (Pixwin__l, 5, font_offset(font) + font_height (font) , 

PIX_SRC, font, buf); 


static void 
draw_canvas_3() 

{ 

char buf[64]; 


sprintf(buf, "%d characters wide". 


pw__text (Pixwin_3, 
pw_text(Pixwin_3, 


} 


CANVAS_3_C0LUMNS); 

5, font__offset (font) , PIX_SRC, font, 

"This subwindow is always 
5, font_offset(font) + font_height(font) 
font, buf); 


PIX_SRC, 
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A.7. detool detool is a simple reverse-polish notation calculator which demonstrates how to 

use pipes to write a SunView-based front end for an existing non-SunView pro¬ 
gram. detool consists of a panel with buttons for each digit, the four arithmetic 
operations, and an enter key. The digits you hit are displayed in a message item 
and are sent via a pipe to ,dc(l) a UNIX desk calculator. When dc computes an 
answer, it is sent back to detool via a second pipe and it is displayed. 

Note also the use of a single notify procedure for all of the digit buttons. The 
actual digit associated with each button is stored as the client data for each panel 
item, so the notify procedure can determine which button was pressed by looking 
at the client data. This value is then passed directly to dc. The operation buttons 
also all use a single notify procedure. 

When you run detool, remember that it is a reverse-polish notation calculator. 

For instance, to compute 3*5 you must hit the buttons 3, Enter, 5, and * in that 
order. If you prefer infix notation, you could easily adapt detool to use bc(l) 
instead of dc. 
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/****************************************************************/ 
#ifndef lint 

static char sccsid[] = M @(#)detool.c 1.4 86/09/15 Copyr 1986 Sun Micro"; 
#endif 

/****************************************************************/ 


♦include <stdio.h> 

♦include <suntool/sunview.h> 
♦include <suntool/panel.h> 


static 

Frame 

frame; 




static 

Panel 

panel; 




static 

Panel_ 

item digit_item[10] 

, enter_ 

item; 

static 

Panel_ 

item add_item, sub_ 

item, mul_item, div__item; 

static 

Panel_ 

item display_item; 




static 

char 

display_buf[512] 

= 

ii ii. 
t 

/* storage for the 






* numbers currently on 






* the display (stored as 






* a string) */ 

static 

FILE 

*fp_tochild; 

/* 

fp of 

pipe to child (write 




* 

data 

on it) * / 

static 

FILE 

*fp__fromchild; 

/* 

fp of 

pipe from child (read 




* 

data 

from it) */ 

static 

int 

tochild; 

/* 

associated file descriptors */ 

static 

int 

fromchild; 




static 

int 

chi1dpid; 

/* 

pid of child process */ 

static 

int 

dead =* 0; 

/* 

set to 1 if child process has 




★ 

died 

*/ 


main(arge, argv) 

int arge; 

char **argv; 

{ 

static Notify_value pipe_reader(); 
static Notify_value dead__child() ; 

frame = window_create(NULL, FRAME, 

FRAME_ARGS, arge, a rgv, 

WIN_ERROR__MSG, "Cannot create frame", 
FRAME_LABEL, "detool - RPN Calculator", 
0 ); 

panel = window_create (frame, PANEL, 

0 ); 

create_panel_iterns (panel) ; 

window_fit (panel) ; 
window_fit (frame) ; 

/* start the child process and tell the notifier about it */ 
start_dc () ; 

/* 

* note that notify_set__input_func takes a file descriptor, 

* not a file pointer used by the standard I/O library 
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*/ 

(void) not if y_set_input_func (frame, pipe_reader, fromchild); 
(void) notify_set_wait3__func (frame, dead__child, childpid); 

window__main_loop (frame) ; 
exit (0); 


static 

create_panel_items (panel) 
Panel panel; 

{ 


int 

char 

static void 
static struct 
int 

} 


c; 

name [2] ; 
digit_proc () 

col, row; 
positions[10] 


op_proc () ; 


{ 0 , 3 }, { 

o. 

0 


{ 

6, 

0 

}, 

{ 

12, 

0 

}, 

{ 

o. 

1 

>, 

{ 

6, 

1 

}, 

{ 

12, 

1 

}, 

{ 

}; 

0 , 

2 


{ 

6, 

2 

>, 

{ 

12, 

2 

) 


name[l] « ' \0 '; 

for (c =0; c < 10; C++) { 

name[0] = c + 'O'; 

digit_item[c] * panel__create_itern (panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, name, 3, 0), 
P ANEL__NOTIFY_PR0C, digit_proc, 

P ANEL__CL I ENT_D ATA, (caddr_t) (c + '0'), 

PANE L_LABE L_X, ATTR_COL(positions[c] .col), 

PANE L_LABE L_Y, ATTR_R0W(positions[c] .row), 

0); 

} 

add_item = panel__create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "+", 3, 0), 
PANEL_NOTIFY_PROC, op_proc, 

PANEL_CLIENT_DATA, (caddr_t) ' +' , 

PANE L__LABE L__X, ATTR__C0L (18), 

PANEL_LABEL_Y, ATTR_R0W (0) , 

0); 

sub_item = panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, " - ", 3, 0), 

PANEL_NOTIFY_PR0C, op_proc, 

PANEL_CLIENT_DATA, (caddr_t) ', 

PANE L_LABE L_X, ATTR_COL(18), 

PANE L_LABE L_Y, ATTR_R0W(1), 

0); 

mul_item = panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, 3, 0), 

PANEL_NOT IFY_PR0C, op_proc, 

PANEL_CLIENT_DATA, (caddr_t) '*', 

PANE L_LABE L_X, ATTR_C0L(18), 

PANE L_LABE L_Y, ATTR_ROW(2), 

0); 

div_item = panel_create_item (panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image (panel, 3, 0), 

P ANEL_N OT IF Y__PR0C, op__proc. 
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P ANEL__CL I ENT__DATA, (caddr_t) ' /' , 

PANEL_LABEL_X, ATTR_COL (18) , 

PANEL_LABEL_Y , ATTR_ROW (3) , 

0); 

enter_item = panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, panel_button_image(panel, "Enter", 7, 0), 
PANEL_NOTIFY_PROC, op_proc, 

PANEL_CLIENT_DATA, (caddr_t) ' ' , 

PANEL_LABEL__X, ATTR_COL (6) , 

PANEL_LABEL_Y, ATTR_R0W (3) , 

0); 

display__item = panel_create_item(panel, PANEL_MESSAGE, 

PANEL_LABE L_STRING, "0", 

PANE L_LABE L_X, ATTR_COL(0), 

PANE L_LABE L_Y, ATTR_ROW(4), 

0); 


/* callback procedure called whenever a digit button is pressed */ 


static void 
digit__proc (item, 
Panel_item 
Event 

{ 

int 


event) 
item; 

*event; 

digit__name 


char 


buf[2]; 


(int) panel_get(item, 

PANEL_CLIENT_DATA); 


buf[0] = digit_name; /* display digit */ 

buf[1] = '\0'; 

streat(display_buf, buf); 

panel_set(display_item, PANEL_LABEL_STRING, display__buf, 0); 
send_to__dc (digit_name); /* send digit to dc */ 


/* 

* callback procedure called whenever an operation button is 

* pressed 
*/ 


static void 

op_proc(item, event) 

Panel_item item; 

Event *event; 

{ 

int op_name = (int) panel_get(item, 

PANEL__CLIENT_DATA) ; 


display__buf [0] = '\0'; 

s end_to_dc (op_name) ; 
if (item != enter_item) 
send_to_dc('p'); 

send_to_dc( f \n'); 


/* don't erase display yet; wait 
* until the answer comes back */ 


/* send a p so the answer will be 
* printed by dc */ 
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/* 

* start the child process 
*/ 

static 
start_dc () 

{ 

int pipeto[2], pipefrom [2]; 

int c f numfds; 

if (pipe(pipeto) < 0 || pipe(pipefrom) < 0) { 

perror("dctool"); 
exit (1); 

} 

switch (childpid - fork()) { 
case -Is 

perror("dctool"); 
exit (1); 

case 0: /* this is the child process */ 

/* 

* use dup2 to set the child's stdin and stdout to the 

* pipes 
*/ 

dup2(pipeto[0] f 0); 
dup2(pipefrom[l] , 1) ; 

/* 

* close all other fds (except stderr) since the child 

* process doesn't know about or need them 
*/ 

numfds * getdtablesize(); 
for (c = 3; c < numfds; C++) 
close (c); 

/* exec the child process */ 
execl("/usr/bin/dc", "dc", 0); 

perror("dctool (child)"); /* shouldn't get here */ 

exit(1); 

default: /* this is the parent */ 

close(pipeto[0]); 
close(pipefrom[l]); 
tochild = pipeto[1]; 
fp_tochild = fdopen(tochild f "w"); 
fromchild = pipefrom[0]; 
fp_fromchild = fdopen(fromchild, "r"); 

/* 

* the pipe to dc must be unbuffered or dc will not get 

* any data until 1024 characters have been sent 
*/ 

setbuf(fp_tochild, NULL); 
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break; 

} 

} 

/* 

* notify proc called whenever there is data to read on the pipe 

* from the child process; in this case it is an answer from dc, 

* so we display it 
*/ 

static Notify_value 

pipe_reader(frame, fd) 

Frame frame; 

int fd; 

{ 

char buf[512]; 

fgets(buf, 512, fp_fromchild); 

buf[strlen(buf) - 1] = f \0';/* remove newline */ 
panel_set (display_item, PANEL_LABEL_STRING, buf, 0); 
display_buf[0] = '\0'; 
return (N0TIFY_D0NE); 

} 

/* 

* notify proc called if the child dies 
*/ 

static Notify_value 

dead_chiId(frame, pid, status, rusage) 

Frame frame; 

int pid; 

union wait *status; 

struct rusage *rusage; 

{ 

panel_set (display_item, PANEL_LABEL_STRING, "Child died! ••, 0) ; 
dead =1; 

/* 

* tell the notifier to stop reading the pipe (since it is 

* invalid now) 

*/ 

(void) notify_set_input_func (frame, NOTIFY_FUNC_NULL, 

fromchild); 

close(tochild); 
close(fromchild); 
return (N0TIFY_D0NE); 

} 

/* send a character over the pipe to dc */ 
static 

s end_t o__dc (c) 

char c; 

{ 

if (dead) 

panel__set (display__item. 
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PANEL_LABEL_STRING, "Child is dead!", 

0 ); 

else 

putc (c, fp_tochild) ; 

} 
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A.8. typein 

This program shows how to replace the functionality of the Graphics Tool and 
gfxsw package previously available under Sun Windows, typein provides a tty 
emulator for interaction with the user and a canvas to draw on. To demonstrate 
it, a simple application is included which allows the user to input coordinates in 
the tty emulator and then draws the vectors in the canvas. 

typein uses a tty subwindow and a canvas. Normally, the tty subwindow is used 
to allow a child process to run in a window; in this case, we would like the same 
process to write in that window. To accomplish this, we tell the tty subwindow 
not to fork a child process with the tty_argv_do_NOT_fork value for 

TTY ARGV. typein uses dup2(2) to set its stdin and stdout to the TTY_FD. 
When the user types something in the tty subwindow, typein 's read_input () 
routine is called. 

NOTE When using this mechanism, be careful of the following problems. First, you 

must use the Notifier (unlike the old gfxsw). Second, if you use the standard I/O 
package, be sure to either use f flush carefully or to remove all buffering with 
setbuf because the package will think you are sending data to a file and not to 
a tty. Finally, be sure you never block on a read because the program will hang 
(either use non-blocking I/O or only read one line at a time). 
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/*********************************************************/ 

#ifndef lint 

static char sccsid[] = "@(#)typein.c 1.5 87/01/07 Copyr 1986 Sun Micro"; 
#endif 

/*********************************************************/ 


♦include <stdio.h> 

♦include <suntool/sunview,h> 
♦include <suntool/canvas.h> 
♦include <suntool/tty.h> 
♦include <ctype.h> 


static Frame 
static Canvas 
static Tty 
static Pixwin 


frame; 

canvas; 

tty; 

*pw; 


static Notify_client my_client; 


♦define STDIN_FD 0 

♦define STD0UT_FD 1 

♦define BUFSIZE 1000 


main(argc, argv) 
int argc; 

char **argv; 

{ 

static Notify_value read_input (); 
int tty_fd; 

frame = window_create(NULL, FRAME, 

FRAME__ARGS, argc, argv, 

WIN_ERROR_MSG, "Cannot create frame", 
FRAME_LABEL, "typein", 

0 ); 


tty = window__create (frame, TTY, 

WI N_PERCENT__HE IGHT, 50, 

T TY_ARGV, TTY_ARGV_DO_NOT_FORK, 

0 ); 


tty_fd = (int) window_get (tty, TTY_TTY_FD) ; 
dup2(tty_fd, STD0UT_FD); 
dup2(tty_fd, STDIN_FD); 

canvas = window_create(frame, CANVAS, 

0 ); 

pw = canvas_pixwin(canvas); 


/* 

* Set up a notify proc so that whenever there is input to read on 

* stdin (fd 0), we are called to read it. 

* Notifier needs a unique handle: give it the address of tty. 

*/ 

my_client = (Notify_client) &tty; 

notify_set_input_func(my_client, read__input, STDIN_FD); 
printf("Enter first coordinate:\nx? "); 
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window_main_loop (frame) ; 
exit (0); 


/* 

* This section implements a simple application which writes prompts to 

* stdin and reads coordinates from stdout, drawing vectors with the 

* supplied coordinates. It uses a state machine to keep track of what 

* number to read next. 


*/ 

#define GET_X_1 0 
#define GET_Y__1 1 
#define GET_X_2 2 
#define GET Y 2 3 


int state = GET_X_1; 
int xl, yl, x2, y2; 


/* ARGSUSED */ 
static Notify__value 
read_input (client, in_fd) 
Notify_client client; 
int in_fd; 

{ 


char buf[BUFSIZE]; 
char *ptr, *gets(); 


/* unused since this must be from ttysw */ 
/* unused since this is stdin */ 


ptr = gets(buf); /* read one line per call so that we 

don't ever block */ 

/* ~ does this matter any more?? */ 

/* handle end of file */ 
if (ptr==NULL) { 

/* Note: could have been a read error */ 
window_set(frame, FRAME_N0_C0NFIRM, TRUE, 0); 
window_done(tty); 

} else { 

switch (state) { 
case GET__X_1: 

if (sscanf(buf, "%d", &xl) != 1) { 

printf("Illegal value!\nx? "); 
fflush(stdout); 

} else { 

printf("y? "); 
fflush(stdout); 
state++; 

} 

break; 

case GET_Y_1: 

if (sscanf(buf, ’^d”, &yl) != 1) { 

printf("Illegal value!\ny? "); 
fflush(stdout); 

} else { 

printf("Enter second coordinate:\nx? "); 

fflush(stdout); 

state++; 

} 

break; 

case GET X 2: 
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if (sscanf(buf, "%d", &x2) != 1) { 

printf("Illegal value!\nx? "); 
fflush(stdout); 

} else { 


} 

break; 

printf("y? "); 
fflush(stdout); 
state++; 


case GET__Y__2: 

if (sscanf(buf, "%d", &y2) != 1) { 


} else 

printf("Illegal value!\ny? "); 
fflush(stdout); 

{ 

printf("Vector from (%d, %d) to (%d f %d)\n" f 
xl r ylf x2 , y2); 

pw_vector(pw f xl f yl f x2, y2 f PIX_SET f 1); 
printf("\nEnter first coordinate:\nx? "); 
fflush(stdout); 
state = GET_X_1; 

} 

break; 

} 

} 

return(NOTIFY_DONE); 

} 
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A.9. Programs that 
Manipulate Color 


The following two programs work with color. You can run them on a mono¬ 
chrome workstation to no ill-effect, but you won’t see much of interest. 


The techniques employed by these two programs are explained in the Color sec¬ 
tion of Chapter 7, Imaging Facilities: Pixwins. 

When using these programs, try invoking them with different colors using the 
frame’s command line arguments. Also, run showcolor (listed in the pixwin 
chapter) to see how the screen’s colormap changes as different color programs 
are run simultaneously. 


coloredit 


The first program, coloredit , puts up sliders that let the user modify its colors. 
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/***************************************************************************/ 
#ifndef lint 

static char sccsid[] * "@ (♦)coloredit.c 1.4 86/09/15 Copyr 1986 Sun Micro”; 
#endif 

/***************************************************************************/ 


♦include <suntool/sunview.h> 
♦include <suntool/panel.h> 
♦include <suntool/canvas.h> 

♦define MYFRAME 0 

♦define MYPANEL 1 

♦define MYCANVAS 2 


/* colormap sizes for the three windows. Canvas is still the biggest 
mycms_sizes[3] = { 

2, 2, 4 

}; 


♦define MYCMS_SIZE 4 

/* color arrays; initialize them with the canvas colors */ 
unsigned char red[MYCMS_SIZE] = {0, 0, 255, 255}; 
unsigned char green[MYCMS_SIZE] = {0, 255, 0, 192}; 
unsigned char blue[MYCMS_SIZE] = {255, 0, 0, 192}; 


*/ 


static void 
static void 
static void 
static void 
static void 
static void 


getcms (); 
setcms () ; 
cycle () ; 
editcms () ; 
set_color () ; 
change_value(); 


Panel_item text_item; 

Panel_item color_item; 

Panel_item red_item, green_item, blue_item; 


Pixwin *pixwins[3]; 

Pixwin *pw; 


main(argc, argv) 
int 
char 

{ 

Frame 

Panel 

Canvas 


argc; 

**argv; 

base__frame; 

panel; 

canvas; 


Attr__avlist sliderdefaults; 

/* the cmsname is copied, so this array can be reused */ 
char cmsname[CMS_NAMESIZE]; 


int counter; 

int xposition; 

char buf[40]; 


base_frame = window_create(NULL, FRAME, 

FRAME LABEL, "coloredit”. 
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FRAME_ARGS, argc, argv, 

0 ); 


/* set up the panel */ 

panel = window_create(base_frame, PANEL, 

0 ); " 


/* create a reusable attribute list for my slider attributes 
sliderdefaults = attr_create_list( 


PANEL_SHOW_ITEM, 

P ANEL_M I N__VALUE , 

P ANEL_MAX__VALUE , 

P ANEL__SL I DER_WI DTH, 
PANEL_SHOW_RANGE, 

PANEL_SHOW_VALUE, 

P ANEL_N0T IF Y__LEVEL, 

0 ); 


TRUE, 

0 , 

255, 

512, 

TRUE, 

TRUE, 

PANEL_ALL, 


*/ 


panel_create_item(panel, PANEL_CYCLE, 
PANEL__LABEL_STRING, 
PANEL__VALUE, 
PANEL_CHOICE_STRINGS, 
PANEL_N0T IFY_PR0C, 

0 ); 


"Edit colormap:", 
MYCANVAS, 

"Frame", "Panel", 
editerns. 


"Canvas", 


Or 


text_item = panel_create__item(panel, PANEL_TEXT, 

P ANEL_VALUE_D ISP LAY__LEN GTH, CMS_NAMESI ZE, 
PANEL_VALUE_STORED_LENGTH, CMS_NAME SIZE, 
0 ); 


color_item = panel_create_item(panel, PANEL_SLIDER, 

ATTR_LIST, 
PANEL_LABEL_STRING, 
PANEL_NOTIFY_PROC, 
0 ); 


sliderdefaults, 
"color:", 
set_color. 


red_item = panel_create_itern (panel, PANEL_SLIDER, 

ATTR_LIST, 

PANEL_LABEL_STRING, 
PANEL_NOTIFY_PROC, 
0 ); 


sliderdefaults, 
" red:", 
change__value, 


green_item = panel_create_item(panel, PANEL_SLIDER, 

ATTR_LIST, sliderdefaults, 

PANEL_LABEL_STRING, "green:", 
PANEL_NOTIFY_PROC, change_value, 

0 ); 


blue_item = panel_create__item (panel, PANEL_SLIDER, 

ATTR__LIST, sliderdefaults, 

P ANEL__LABE L__S TRI NG, " blue:", 

P ANEL_NOT I FY___PROC, change_value, 

0 ); 

panel_create_item(panel, PANEL_BUTTON, 

PANEL_LABEL_IMAGE, 
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panel__button_image (panel, "Cycle colormap", 12, NULL), 
PANE L_N OTIFY_PROC, cycle, 

0 ); 


window_fit(panel); 

window_fit_width(base_frame); 

/* free the slider attribute list */ 
free(sliderdefaults); 

/* set up the canvas */ 

canvas = window_create (base_frame, CANVAS, 0); 

/* get pixwins */ 

pixwins[MYFRAME] = (Pixwin *) window_get(base_frame, WIN_PIXWIN); 
pixwins[MYPANEL] = (Pixwin *) window_get(panel, WIN_PIXWIN); 
pw = pixwins[MYCANVAS] = (Pixwin *) canvas_pixwin(canvas); 

/* set up the canvas' colormap */ 

sprintf(cmsname, "coloredit%D", getpid()); 

pw_set cmsname(pw, cmsname); 

pw_putcolormap(pw, 0, mycms_sizes[MYCANVAS], red, green, blue); 

/* draw in the canvas */ 

/* don't draw color 0 — it is the background */ 
for (counter = 1; counter < mycms_sizes[MYCANVAS]; counter+f) { 
xposition = counter * 100; 
pw_rop(pw, xposition, 50, 50, 50, 

PIX_SRC | PIX__C0L0R(counter) , NULL, 0, 0); 
sprintf(buf, "%d", counter); 

pw__text (pw, xposition + 5, 70, PIX_SRC ~ PIX_DST, 0, buf); 

} 

pw__text (pw, 100, 150, 

PIX_SRC | PIX_COLOR(mycms_sizes[MYCANVAS] -1), 0, 

"This is written in the foreground color"); 

/* initialize to edit the first canvas color */ 
editcms(NULL, MYCANVAS, NULL); 

window_main_loop (base_frame) ; 
exit (0); 


static int cur_cms = -1; 

/* ARGSUSED */ 
static void 

editcms(item, value, event) 

Panel_item item; 

unsigned int value; 

Event *event; 

{ 

int planes; 

struct colormapseg cms; 

char cmsname[CMS_NAMESIZE]; 

if (value == cur_cms) 
return; 
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cur_cms = value; 

/* get the new cmsname */ 

pw_getcmsname(pixwins[cur_cms], cmsname); 
panel_set_value (text_item, cmsname) ; 

pw = pixwins [cur_cms] ; 

/* get the new colormap */ 

/* 

* first have to get its size there is NO DOCUMENTED procedure to do 

* this. 

*/ 

pw_getcmsdata(pw, &cms, &planes); 


pw_getcolormap(pw, 0, cms.cms^size, red, green, blue); 

panel_set (color__item, 

PANEL_VALUE, 0, 

PANEL_MAX_VALUE, cms.cms_size - 1, 

0 ); 

/* call the proc to set the colors */ 
set_color(NULL, 0, NULL); 


int cur_color; 

/* ARGSUSED */ 
static void 

set__color (item, color, event) 

Panel_item item; 

unsigned int color; 

struct inputevent *event; 

{ 

panel_set_value(red_item, red[color]); 
panel_set_value(green_item, green[color]); 
panel_set_value(blue_item, blue[color]); 
cur_color = (unsigned char) color; 

} 


/* ARGSUSED */ 
static void 

change_value(item, value, event) 
Panel__item item; 

int value; 

struct inputevent *event; 


{ 


if (item == red_item) 

red[cur_color] = (unsigned char) value; 
else if (item == green_item) 

green[cur_color] = (unsigned char) value; 

else 

blue[cur_color] = (unsigned char) value; 

/* 

* pw_putcolormap expects arrays of colors, but this only sets one 

* color 
*/ 

pw_jputcolormap (pw, cur_color, 1, 

&red[cur_color], Sgreen[cur_color], &blue[cur_color]); 
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/* ARGSUSED */ 
static void 
cycle(item, event) 

Panel_item item; 

Event *event; 

{ 

pw_cyclecolormap (pw, 1, 0, mycms_sizes [cur_cms]) ; 

} 

^_ _ _—- 
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animatecolor 


This program demonstrates smooth animation via the technique of software 
double-buffering. Two colormaps for the canvas are set up so that while one is 
being written two, the other is being displayed. This allows smoother animation. 

The routines that set up the colormaps and swap them, doublebuf f_init () 
and doublebuf f_swap (), are general enough to be used in other programs 
that alternate two colormaps. You need only set up a similar colorstuf f 
structure to use these routines in another program. 

The logic involved in creating the colormaps is complex. The colormaps created 
for animatecolor are given in the table Sample Colormap to Isolate Planes in the 
pixwin chapter. 
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/***************************************************************/ 
tifndef lint 

static char sccsid[] = "@(#)animatecolor.c 1.4 88/03/09 Copyr 1986 Sun Micro"; 
#endif 

/***************************************************************/ 

#include <suntool/sunview.h> 
tinclude <suntool/canvas.h> 


/***************************************************************/ 
/* You set MYCOLORS & MYNBITS according to how many colors */ 

/* you are using; rest is just boilerplate, more or less; */ 

/* it you define your colors. */ 

/★a*************************************************************/ 

/* 

* define the colors I want in the canvas; max 16, must be a 

* power of 2 
*/ 

#define MYCOLORS 4 

/* 

* define the number of bits my colors take up — MYCOLORS log 2; 

* maximum for animation to be possible is half screen's bits per 

* pixel — 4 bits on current Sun color displays. 

*/ 

#define MYNBITS 2 

/* 

* to "hide" one set of planes while displaying another takes a 

* large cms — the square of the number of colors 
*/ 

#define MYCMS_SIZE (MYCOLORS * MYCOLORS) 

/* 

* when you write out a color pixel, you must write the color in 

* the appropriate planes. This macro writes it in both sets 
*/ 

#define usecolor(i) ( (i) | ((i) « colorstuff.colorbits) ) 

struct colorstuff { 

/* desired colors */ 

unsigned char redcolors[MYCOLORS] ; 

unsigned char greencolors[MYCOLORS]; 

unsigned char bluecolors[MYCOLORS]; 

/* number of bits the desired colors take up */ 
int colorbits; 

/* colormap segment size */ 
int cms__size; 

/* 2 colormaps to support it */ 
unsigned char red[2][MYCMS_SIZE]; 

unsigned char green[2][MYCMS_SIZE]; 

unsigned char blue[2][MYCMS_SIZE]; 

/* 2 masks to support it */ 
int enable__0_mask; 

int enable_l__mask; 

/* current colormap — 0 or 1 */ 
int cur_buff; 

/* plane mask to control which planes are written to */ 
int plane_mask; 
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In¬ 


struct colorstuff colorstuff 
/* desired red colors */ 

/* desired green colors */ 

/* desired blue colors */ 


{ 


{0, 0, 255, 
{0, 255, 0, 


{255, 0, 0, 

/* number of planes these colors take up */ 


MYNBITS, 


/* colormap segment size */ 

MYCMS_SIZE, 

/* rest filled in later */ 

}; 


255}, 

192}, 

192}, 


static void resize_proc(); 

/* stuff needed to do random numbers */ 


extern 

void 

s random () ; 

extern 

int 

getpid() ; 

extern 

long 

random(); 

extern 

char 

* sprint f () ; 


static Notify_value my_frame_interposer(); 
static Notify_value my_draw(); 

static Pixwin *pw; 

static int times_drawn; 

static int Xmax, Ymax; 

main (argc, argv) 

int argc; 

char **argv; 

{ 

F rame ba s e_f rame; 

Canva s canva s; 

base_frame = window_create(NULL, FRAME, 

FRAME_LABEL, "animatecolor”, 
FRAME_ARGS, argc, argv, 

0 ); 

canvas = window_create(base_frame, CANVAS, 

CANVAS_RETAINED, TRUE, 

CANVAS_RE SIZE_PR0C, re siz e_proc, 

0 ); 

pw = (Pixwin *) canvas_pixwin(canvas); 

/* set up the canvas' colormap */ 
doublebuff_init(Scolorstuff); 

/* run the drawing routine as often as possible */ 

(void) notify_set_itimer_func (base__frame, my__draw, 

ITIMER_REAL, 

&NOTIFY_POLLING_ITIMER, 

( (struct itimerval *) 0) ); 

/* initialize the random function */ 
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srandom(getpid ()); 
window_main_loop (base_f rame) ; 
exit(0); 

} 

/* ARGSUSED */ 

static Notify__value 

my_draw(client, itimer_type) 

Notify_client client; 
int itimer__type; 

{ 

/* 

* draw the squares, then swap the colormap to animate them 

V 

#define SQUARESIZE 50 

#define MAX_VEL (SQUARESIZE / 5) 

/* number of squares to animate */ 

#define NUMBER (MYCOLORS - 1) 


static int 
static int 
static int 
int 


posx[NUMBER], posy[NUMBER]; 

vx[NUMBER], vy[NUMBER]; 

prevposx[NUMBER], prevposy[NUMBER]; 

i; 


/* set the plane mask to be that which we are not viewing */ 
pw_putattributes(pw, (colorstuff.cur_buff == 1) ? 

&(colorstuff.enable_l_mask): &(colorstuff.enable_0__mask)); 

/* write to invisible planes */ 
for (i - 0; i < NUMBER; i++) { 

if (!times_drawn) { 

/* first time drawing */ 

posx[i] = (i + 1) * 100; 
posy[i] = 50; 

vx[i] = r(-MAX_VEL, MAX_VEL); 
vy[i] = r(-MAX_VEL, MAX_VEL); 

} 

if (abs(vx[i]) > MAX_VEL) { 

printf("Weird value (%d) for vx[%d]\n" f vx[i], i); 
vx [i] = r (-MAX__VEL, MAX_VEL) ; 

} 

posx[i] = posx[i] + vx[i]; 
if (posx[i] < 0) { 

/* Bounce off the left wall */ 
posx[i] =0; 
vx[i] = -vx[i]; 

} else if (posx[i] > Xmax - SQUARESIZE) { 

/* Bounce off the right wall */ 

vx[i] = -vx[i]; 

posx[i] = posx[i] + vx[i]; 

} 

posy[i] = posy[i] + vy[i]; 
if (posy[i] > Ymax - SQUARESIZE) { 

/* Bounce off the top */ 
posy[i] = Ymax - SQUARESIZE; 
vy[i] = -vy[i]; 

} else if (posy[i] < 0) { 
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/* Bounce off the bottom */ 
posy[i] *= 0; 
vy[i] = -vy[i]; 

} 

/* draw the square you can't see */ 

pw_rop(pw, posx[i] f posy[i], SQUARESIZE, SQUARESIZE, 

PIX_SRC | PIX_C0L0R (usecolor (i + 1) ) , NULL, 0, 0) ; 

} 

/* 

* swap the colormaps, and hey presto! should appear smoothly 
*/ 

doublebuff_swap(Scolorstuff); 
times_drawn++; 

/* set the plane mask to be that which we are not viewing */ 
pw_j?utattributes (pw, (colorstuff. cur_buff == 1) ? 

&(colorstuff.enable_l_mask): &(colorstuff.enable_0_mask)); 

/* erase now invisible planes */ 
for (i - 0; i < NUMBER; i++) { 

if (times__drawn >1) { 

/* squares have been drawn before */ 

/* erase in the one you can't see */ 
pw_rop(pw, prevpo sx[i], prevpo sy[i], 

SQUARESIZE, SQUARESIZE, PIX__CLR, NULL, 0, 0) ; 

} 

/* remember so can erase later */ 
prevposx[i] = posx[i]; 
prevposy[i] = posy[i]; 

} 

/* 

* set the plane mask to be that which we are viewing, in 

* case screen has to be repaired between now an when we are 

* called again. 

*/ 

pw_putattributes(pw, (colorstuff.cur_buff == 1) ? 

& (colorstuff. enable_0_mask) : & (colorstuff. enable__l__mask)) ; 


} 


/* random number calculator */ 
int 


r(minr, maxr) 


int 

minr 

{ 


int 

i; 


i * random () % (maxr - minr + 1); 
if (i < 0) 

return (i + maxr + 1); 

else 

return (i + minr); 

} 
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/* ARGSUNUSED */ 
static void 

resize_j>roc(canvas, width, height) 

{ 

times_drawn = 0; 

/* remember, pixels start at 0, not 1, in the pixwin */ 

Xmax = width - 1; 

Ymax = height - 1; 

} 

/* 

* Do double buffering by changing the write enable planes and 

* the color maps. The application draws into a buffer which is 

* not visible and when the buffers are swapped the invisible one 

* become visible and the other become invis. 

* 

* Start out drawing into buffer 1 which is the low-order buffer; 

* ie. the low-order planes. Things would not work if this is not 

* done because the devices start out be drawing with color 1 

* which will only hit the low-order planes. 

* 

* Init double buffering: Allocate color maps for both buffers. Fill 

* in color maps. 

*/ 

doublebuff_init(colorstuff) 

struct colorstuff ^colorstuff; 

{ 

/* 

* user has defined desired colors. Set them up in the two 


* colormap 

segments 

*/ 


int 

index__l ; 

int 

index__2; 

int 

i; 

char 

cmsname [CMS_NAMESIZE] ; 


/* name colormap something unique */ 
sprintf (cmsname, ,, animatecolor%D", getpid()) ; 
pw_setcmsname (pw, cmsname); 

/* 

* for each index in each color table, figure out how it maps 

* into the original color table. 

*/ 

for (i =0; i < colorstuff->cms_size; i++) { 

/* 

* first colormap will show color X whenever low order 

* bits of color index are X 
*/ 

index__l = i & ( (1 « colorstuff->colorbits) - 1); 

/* 

* second colormap will show color X whenever high order 

* bits of color index are X 
*/ 

index 2 = i » colorstuff->colorbits; 
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colorstuff->red[0][i] = colorstuff->redcolors[index_l]; 
colorstuff->green[0][i] = colorstuff->greencolors[index_l]; 
colorstuff->blue[0][i] = colorstuff->bluecolors[index_l]; 

colorstuff->red[l][i] = colorstuff->redcolors[index_2]; 
colorstuff->green[1][i] = colorstuff->greencolors[index_2]; 
colorstuff->blue[1][i] = colorstuff->bluecolors[index_2]; 

} 

colorstuf f->enable__l__mask = ( (1 « colorstuff->colorbits) - 1) 
« colorstuff->colorbits; 

colorstuff->enable__0_mask = ((1 « colorstuff->colorbits) - 1); 
/* 

* doublebuff_swap sets up the colormap. We want the drawing 

* to start off drawing into the 1st buffer, so set the 

* current buffer to 1 so that when doublebuff_swap is called 

* it will set up the first ([0] ) colormap. 

*/ 

colorstuf f->cur__buff == 1; 
doublebuf f__swap (colorstuff) ; 


* Routine to swap buffers by loading a color map that will show 

* the contents of the buffer that was not visible. Also, set the 

* write enable plane so that future writes will only effect the 

* planes which are not visible. 

*/ 

doublebuff_swap(colorstuff) 

struct colorstuff *colorstuff; 

{ 

if (colorstuff->cur_buff == 0) { 

/* display first buffer while writing to 2nd */ 

/* 

* Careful! pw_jputcolormap () wants an array or pointer 

* passed, but the colormap arrays are 2-d 
*/ 

pw_j?utcolormap(pw, 0, colorstuff->cms_size, 
colorstuff->red[0], 
colorstuff->green[0], 
colorstuff->blue[0]); 

/* set plane mask to write to second buffer */ 
colorstuff->plane_mask = colorstuff->enable_l_mask; 
colorstuff->cur_buff = 1; 

} else { 

/* display second buffer while writing to first */ 
pw_jputcolormap(pw, 0, colorstuff->cms_size, 
colorstuff->red[1], 
colorstuff->green[1], 
colorstuff->blue[1]); 


/* set plane mask to write to first buffer */ 
colorstuff->plane_mask = colorstuff->enable_0_mask; 
colorstuff->cur_buff = 0; 

} 

} 
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A.10. Two gfx 

subwindow-based 
programs converted 
to use SunView 


The following two programs are the Sun demo programs bouncedemo and 
spheresdemo converted from using gf xsw_init () to canvases in SunView. 

The code for the SunWindows-based programs is in 

/usr / share/src/sun/suntool so you can contrast that code with the 

SunView versions printed here. 

Techniques used to convert programs such as these to SunView 1 are described 
in Appendix C, Converting SunWindows Programs to SunView. 


bounce The first program is bouncedemo converted to draw in a canvas and to call 

notif y_dispatch () periodically. Like the original bouncedemo, it restarts 
drawing after any damage (if not retained) or resizing. 
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#ifndef lint 

static char sccsid[] = "@(#)bounce.c 1.5 88/02/26 Copyr 1986 Sun Micro"; 
#endif 


/* 

* Overview: Bouncing ball demo in window. 

* Converted to use SunView by simulating the gfxsubwindow structure. 
*/ 


/* this replaces all includes */ 

#include <suntool/sunview.h> 

#include <suntool/canvas.h> 

/* straight from the Canvas chapter */ 
static void repaint_proc(); 

static void resize_proc(); 

/* straight from the Notifier chapter */ 
static Notify_value my_notice_destroy(); 
extern Notify_error notify_dispatch(); 


static int 


my_done; 


/* define my own gfxsubwindow struct */ 
struct gfxsubwindow { 
int 

#define GFX_RESTART 
#define GFX_DAMAGED 
int 

struct pixwin 
struct rect 


gfx_flags; 

0x01 

0x02 

gfx_reps; 

*gfx_pixwin; 

gfx_rect; 


} 


mygfx; 


struct gfxsubwindow *gfx = &mygfx; 
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main(argc, argv) 
int 
char 


argc; 

*argv; 


short x, y, vx, vy, z, ylastcount, ylast; 

short Xmax, Ymax, size; 

/* WIN_RECT attribute returns a pointer */ 

Rect *rect; 

/* have to handle this arg that gfxsw_init used to process */ 
int retained; 

/* 

* replace this call if (gfx == (struct gfxsubwindow *)0) exit(l); 

* with ... 

*/ 


Frame 

Canvas 

Pixwin 


frame; 

canvas; 

*pw; 


/* this arg was also dealt with by gfxsw_init */ 
gfx->gfx_reps = 200000; 

frame = window_create(NULL, FRAME, 

FRAME_LABEL, "bounce", 

FRAME_ARGC_P TR_ARGV, &argc, argv, 

WIN_ERR0R_MSG, "Can't create frame", 

0 ); 

for (—argc, ++argv; *argv; argv++) { 

/* 

* handle the arguments that gfxsw_init (0, argv) used to do 

* for you 
*/ 

if (strcmp(*argv, "-r") == 0) 
retained =1; 

if (strcmp(*argv, "-n") == 0) 
if (argc > 1) { 

(void) sscanf(*(++argv), "%hD", &gfx->gfx_reps); 
argc++; 

} 

} 

canvas = window_create(frame, CANVAS, 

CANVAS_RETAINED, retained, 

CANVAS__RE SIZ E_P ROC, resize_jproc, 

CANVAS_FA S T_M0N 0, TRUE, 

WIN_ERROR_MSG, "Can't create canvas", 

0 ); 

/* only need to define a repaint proc if not retained */ 
if (!retained) { 

window_set(canvas, 

CANVAS_REPAINT_PROC, repaint_proc, 

0 ); 

} 

pw = canvas_pixwin(canvas); 
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gfx->gfx_jpixwin = canvas_pixwin(canvas); 

/* Interpose my proc so I know that the tool is going away. */ 
(void) notify_interpose_destroy_func(frame, my__notice_destroy) ; 

/* 

* Note: instead of window_main_loop, just show the frame. The 

* drawing loop is in control, not the notifier. 

*/ 

window_set (frame, WIN_SHOW, TRUE, 0); 
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Restart: 

rect = (Rect *) window_get(canvas, WIN_RECT); 

Xmax = rect_right(rect); 

Ymax = rect__bottom(rect) ; 
if (Xmax < Ymax) 

size = Xmax / 29 + 1; 

else 

size = Ymax / 29 + 1; 

/* 

* the following were always 0 in a gfx subwindow (bouncedemo 

* is confused on this point 
*/ 

x = 0; 
y = 0; 


vx = 4; 
vy = 0; 
ylast = 0; 
ylastcount = 0; 

pw_writebackground(pw, 0, 0, rect->r_width, rect->r__height, 
PIX_SRC); 

/* 

* Call notify_dispatch() to dispatch events to the frame 

* regularly. This will call my resize and repaint procs and 

* interposed notify_destroy__func if necessary. The latter will 

* set my__done to TRUE if it's time to finish. 

*/ 

while (gfx->gfx_reps) { 

(void) notify_dispatch(); 
if (my_done) 

break; 


/* 

* this program is not concerned with damage, because either 

* the canvas repairs the damage (if retained) or it just 

* restarts, which is handled by GFX_RESTART 
*/ 

/* 

* if (gfx->gfx_flags&GFX__DAMAGED) gfxsw_handlesigwinch(gfx); 
*/ 

if (gfx->gfx__flags & GFX_RESTART) { 

gfx->gfx_flags &= ~ GFX_RESTART; 
goto Restart; 

} 

if (y == ylast) { 

if (ylastcount++ > 5) 
goto Reset; 

} else { 

ylast = y; 
ylastcount =0; 

} 

pw_writebackground(pw, x, y, size, size, 

PIX__N0T (PIX_DST) ) ; 

x = x + vx; 

if (x > (Xmax - size)) { 

s /* 

* Bounce off the right edge 
*/ 

x = 2 * (Xmax - size) - x; 


m sun 

XT microsystems 


Revision A, of May 9, 1988 





Appendix A — Example Programs (bounce) 459 



r 


vx = -vx; 

} else if (x < 0) { 

/* 

* bounce off the left edge 
*/ 

x = -x; 
vx = -vx; 

} 

vy = vy + 1; 
y - Y + vy; 

if (y >= (Ymax - size)) { 


/* 


* bounce off the bottom edge 


*/ 

y = Ymax - size; 
if (vy < size) 


vy = 1 - vy; 

else 

vy = vy / size - vy, 
if (vy == 0) 

goto Reset; 


} 

for (z = 0; z <= 1000; z++) ; 
continue; 


Reset: 



if (—gfx->gfx_reps <= 0) 
break; 


x = 0; 
y = 0; 
vx = 4; 
vy = 0; 


ylast =0; 
ylastcount = 0; 


} 



V. 
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static void 

repaint_proc( /* Ignore args */ ) 

{ 

/* if repainting is required, just restart */ 
gfx->gfx_flags |= GFX_RESTART; 

} 

static void 

resize_proc( /* Ignore args */ ) 

{ 

gfx->gfx__flags |= GFX_RESTART; 

} 

/* this is straight from the Notifier chapter */ 
static Notify_value 

my_notice_destroy(frame, status) 

Frame frame; 

Destroy_status status; 

{ 

if (status != DESTROY_CHECKING) { 

/* set my flag so that I terminate my loop soon */ 
my_done = 1; 

/* Stop the notifier if blocked on read or select */ 
(void) notify_stop(); 

} 

/* Let frame get destroy event */ 

return (notify_next_destroy_func(frame, status)); 

} 
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spheres This is an example of a program that has been converted to use 

window_main_loop (). It displays a fixed-sized image in a canvas that has 
scrollbars. It continues drawing its image when its window is damaged or 
resized. However, it stops drawing when it is iconic. 

You will have to create your own icon for this called spheres . icon. 
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#ifndef lint 

static char sccsid[] = (#)spheres.c 1.4 88/02/05 Copyr 1986 Sun Micro"; 

#endif 
/* 

* spheres — draw a bunch of shaded spheres Algorithm was done 

* by Tom Duff, Lucasfilm Ltd., 1982 

* Revised to use SunView canvas instead of gfxsw. 

*/ 

#include <suntool/sunview.h> 

♦include <suntool/canvas.h> 

♦include <suntool/scrollbar.h> 

♦include <sunwindow/cms_rainbow.h> 

static Notify_value my_frame_interposer(); 
static Notify_value my_animation(); 
static void sphere(); 

static void demoflushbuf(); 


♦define ITIMER NULL 


/* 


* (NX, NY, NZ) is the light source vector 

* 100 
*/ 

♦define NX 48 
♦define NY -36 
♦define NZ 80 


((struct itimerval *)0) 

length should be 


♦define BUF BITWIDTH 


16 


static struct pixrect *mpr; 


static int 
static int 
static int 
static Frame 
static Canvas 
static int 
static Pixwin 


width; 

height; 

counter; 

frame; 

canvas; 

cmssize; 

*pw; 


static short spheres_image[256] = { 

♦include "spheres.icon" 

}; 

mpr_static(spheres_pixrect, 64, 64, 1, spheres_image); 


main(argc, argv) 
int 
char 

{ 

char 

int 

Icon 


argc; 

**argv; 

**args; 

usefullgray = 0; 
icon; 


icon = icon_create(ICON_IMAGE, &spheres_j>ixrect, 0); 
frame * window_create(NULL, FRAME, 

FRAME LABEL, "spheres". 
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FRAME_ICON, icon, 

FRAME_ARGC_PTR_ARGV, & a r g c, argv, 

0); 

canvas = window_create(frame, CANVAS, 

CANVAS_AUTO_EXPAND, 0, 

CANVAS_AUTO_SHRINK, 0, 

CANVAS_AUTO_CLEAR, 0, 

/* 

* Set SCROLL_LINE_HEIGHT to 1 so that clicking LEFT or RIGHT 

* in the scroll buttons scrolls the canvas by one pixel. 

*/ 

WI N_VERT I CAL_S CROLLBAR, scrollbar__create (S CROLL_L I NE_HE I GHT, 1, 

0), 

WIN_HORIZONTAL_SCROLLBAR, scrollbar_create(SCR0LL_LINE_HEIGHT, 1, 

0), 

0); 

for (args = argv; *args; args++) { 
if (strcmp(*args, "-g") == 0) 
usefullgray =1; 

} 

/* Interpose in front of the frame's client event handler */ 

(void) notify_interpose_event_func(frame, my_frame_interposer, 

NOTIFY_SAFE); 

(void) notify_set_itimer_func(frame, my_animation, 

ITIMER_REAL, &NOTIFY_POLLING_ITIMER, ITIMER_NULL); 

width = (int) window_get(canvas, CANVAS__WIDTH) ; 
height = (int) window_get (canvas, CANVAS_HEIGHT) ; 
pw = canvas_j?ixwin (canvas) ; 

cmssize = (usefullgray) ? setupfullgraycolormap(pw) : 
setuprainbowcolormap(pw); 

mpr = mem_create(BUF_BITWIDTH, height, pw->pw_j?ixrect->pr_depth); 
window_main_loop(frame); 
exit(0); 

} 

static int 
static int 
static int 
static int 
static int 
static int 
static int 
static int 
static int 

/* ARGSUSED */ 
static 

my__animation (client, itimer_type) 

Notify_client client; 
int itimer_type; 

{ 

register i; 

if (x >= radius) { 

radius = r(0, min(width / 2, height / 2)); 
xO = r(0, width); 
yO *= r(0, height); 


radius; 

xO; /* x center */ 

y0; /* y center */ 

color; 
x; 

y; 

maxy; 
mark; 
xbuf; 


Notify_value 
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color = r(0, cmssize + counter++) % cmssize; 
x = -radius; 
xbuf = 0; 

/* 

* Don't use background colored sphere. 

*/ 

if (color == 0) 
color++; 

/* 

* Don't use tiny sphere. 

*/ 

if (radius < 8) 
radius = 8; 

} 

for (i =0; i < 5; i++) { 
xbuf++; 

maxy = sqroot(radius * radius - x * x) ; 
pw_vector(pw, xO + x f yO - maxy, xO + x, yO + maxy, 
PIX_CLR, 0); 

for (y = -maxy; y <= maxy; y++) { 

mark = r(0, radius * 100) <= NX * x + NY * y 

+ NZ * sqroot(radius * radius -x*x-y*y); 
if (mark) 

pr_put(mpr, xbuf, y + yO, color); 

} 

if (xbuf == (mpr->pr_width - 1)) { 

demoflushbuf(mpr, PIX_SRC | PIX_DST, 

x + xO - mpr->pr_width, pw); 

xbuf = 0; 
x++; 

return (NOTIFY_DONE); 

} 

x++; 

} 

if (x >= radius) 

demoflushbuf(mpr, PIX_SRC | PIX_DST, x + xO - (xbuf + 2), 
pw) ; 

return (N0TIFY_D0NE); 


static void 

demoflushbuf(mpr, op, x, pixwin) 
struct pixrect *mpr; 
int op; 

int x; 

struct pixwin *pixwin; 

{ 

register u_char *sptr, *end; 

sptr = mprd8_addr (mpr__d (mpr) , 0, 0, mpr->pr_depth) ; 
end = mprd8_addr(mpr_d(mpr), mpr->pr_width - 1, 

mpr->pr_height - 1, mpr->pr_depth); 

/* 

* Flush the mpr to the pixwin. 

*/ 

pw_write(pixwin, x, 0, mpr->pr_width, mpr->pr__height, op. 
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mpr, 0, 0); 

/* 

* Clear mpr with 0's 
*/ 

while (sptr <= end) 

*sptr++ = 0; 

/* Let user interact with tool */ 
notify_dispatch () ; 

} 


static int 

setuprainbowcolormap(pw) 

Pixwin *pw; 

{ 

register u_char red[CMS_RAINBOWSIZE]; 
register u_char green[CMS_RAINBOWSIZE]; 
register u_char blue[CMS_RAINBOWSIZE]; 

/* 

* Initialize to rainbow cms. 

*/ 

pw_setcmsname(pw, CMS_RAINBOW); 
cms_rainbowsetup(red, green, blue); 

pw_putcolormap(pw, 0, CMS_RAINBOWSIZE, red, green, blue); 
return (CMS_RAINBOWSIZE); 

} 

static int 

setupfullgraycolormap(pw) 

Pixwin *pw; 

{ 

#define CMS_FULLGRAYSIZE 256 

#define CMS_FULLGRAY "fullgray" 

register u_char red[CMS__FULLGRAYSIZE] ; 
register u_char green [CMS__FULLGRAYSIZE] ; 
register u_char blue[CMS_FULLGRAYSIZE]; 
register i; 

/* 

* Initialize to rainbow cms. 

*/ 

pw_setcmsname(pw, CMS_FULLGRAY); 
for (i = 0; i < CMS_FULLGRAYSIZE; i++) { 

red[i] = green[i] = blue[i] = i; 

} 

pw_putcolormap(pw, 0, CMS_FULLGRAYSIZE, red, green, blue); 
return (CMS_FULLGRAYSIZE); 

} 


static Notify_value 

my_frame__interposer (frame, event, arg, type) 
Frame frame; 

Event *event; 

Notify_arg arg; 

Notify_event_type type; 

{ 
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r 


int 

Notify_value 


closed_initial, closed_current; 
value; 


/* Determine initial state of frame */ 

closed_initial = (int) window__get (frame, FRAME_CLOSED) ; 

/* Let frame operate on the event */ 

value = notify_next_event_func(frame, event, arg, type); 

/* Determine current state of frame */ 

closed_current = (int) window_get(frame, FRAME_CLOSED) ; 

/* Change animation if states differ */ 
if (closed_initial != closed_current) { 
if (closed_current) { 

/* Turn off animation because closed */ 

(void) notify_set_itimer_func (frame, my__animation. 


ITIMER_REAL, ITIMER_NULL, ITIMER_NULL) 


} else { 


/* Turn on animation because opened */ 

(void) notify_set__itimer_func (frame, my__animation, 

ITI MER__REAL, &NOTIFY_POLLING_ITIMER, 
ITIMER_NULL); 


return (value); 


} 
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B.l. Program Names 


B.2. Frame Headers 


The window programs released by Sun follow some standard user interface con¬ 
ventions. These conventions are described here so that, if you choose, you can 
design your interfaces with them in mind. 

Here are some guidelines for naming programs: 

□ A window-based version of an existing tty-based program has tool appended 
to the end of the existing program. For example mailtool is a window- 
based version of the tty-based program mail(l). 

□ A program without a tty version should not end with tool. Thus the icon edi¬ 
tor is called iconedit and not icontool. 

□ Since tools are normally invoked from command files or menus, descriptive 
names are better than short cryptic ones. Thus iconedit is better than ied. 

The frame header should contain the name of the program, optionally followed 
by a dash and additional information, as in: 


textedit - /tmp/file, dir: /usr/dg/doc 


I I 


B.3. Menus 

Capitalization The words in menus should be capitalized as they would be in a chapter heading: 


Close 
Move ><► 
Resize =» 
Expose 
Hide 

Redisplay 
Quit 


This convention can be bent when the names in the menu correspond to already 
existing, non-capitalized command names. 
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Menus Showing Button 
Modifiers 


Interaction with Standard 
Menus 


Enable/Disable Menu Items 

Multi-Column Menus 

B. 4 . Panels 


When the behavior of a panel button depends on whether the user holds down a 
shift key, the button should have a menu summarizing the different actions, as in 
this menu from the Reply button in mail tool: 


reply 


Reply (all) 

[Shift] 

reply, include 

[Ctrl] 

Reply (all). Include 

[Ctrl][Shi ft] 


Standard SunView menus, such as the frame menu, should not be modified. 

When a user is used to seeing ‘Quit’ at the end of the frame menu, it is confusing 
to see a frame menu with a new item tacked on at the end. Equally confusing is a 
frame menu that comes up with an item other than ‘Close’ at the top. Thus, 
instead of deleting an item from a standard menu, applications should render the 
item inactive and “grayed-out.” And instead of adding a new item to a standard 
menu, applications should make a new menu, with the name of the standard 
menu at the top, followed by the application-specific commands. The standard 
menu then becomes a pullright subordinate to the custom menu, as in the exam¬ 
ple below: 


Frame 

Close 

Dump Sere 

Move + 

Dump Regi 

Resize =* 

Print Dum 

Expose 

View Dump 

Hide 


Redisplay 


Quit 


Sometimes a menu has two different states, with different words appearing in the 
same position in a menu, depending on the current state. When the two states 
correspond to something being on or off, the words ‘Enable’ and ‘Disable’ 
should be used. Thus shelltool uses ‘Enable Page Mode’ and ‘Disable Page 
Mode’. 

Overly long menus should be avoided. Use menus with more than one column 
instead. 

The defaults for panel items given in this section are intended to promote con¬ 
sistency across applications and provide convenient building blocks for program¬ 
mers who don’t want to put a great deal of effort into designing fancy panels. 

The intent is not to rule out the use of non-default panel items. 
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Buttons 


List of Non-Exclusive Choices 


List of Exclusive Choices 


The proper use of buttons is to allow the user to initiate commands. Button items 
should not be used to represent categories, modes or options — for these kinds of 
choices that imply a change of state, you should use toggle, choice or cycle 
items, as described in the next three sections. 

When creating a button, use the routine panel_button_image () to create a 
button-like image, as in: 

{ Dump Screen"**^ 


As with menu entries, capitalize buttons unless the button name matches some¬ 
thing else (for example, dbx(l) commands in dbxtool). If the button’s mean¬ 
ing can be modified by I Control I or I Shift I these modifiers should be indicated in 
the button’s menu. (For an example, see the picture of the Reply menu from 
mail tool, at the top of the preceding page.) 

In most cases, a button will remain visible all the time. However, when a tool 
has different states, and a button can only be used in some of those states, it is 
usually best to make the button invisible when it can not be invoked. Thus in 
mailtool, the Cancel button only appears when a letter is being composed. 

A list of choices in which more than one choice can be selected at a time is best 
implemented with the item type PANEL_TOGGLE. The default for toggles is a 
list of check boxes: 

Optional Software: 

E?' Database 

□ Demos 

^Document Preparation Tools 

□ Games 

0^Productivity Tools 

The example shows a vertical list; vertical or horizontal are both acceptable. 

A list of choices in which only one choice can be selected at a time can be 
displayed with all choices visible or with only the current choice visible. To 
show all the choices, use the item type PANEL_CH0ICE. The default for choice 
items is a list of square pushbuttons, with the current choice marked by a dark¬ 
ened pushbutton: 

Drawing Mode: a Point a Line a Rectangle a Circle a Text 

To show only the current choice, use PANEL_CYCLE. This item type provides a 
symbol consisting of two circular arrows, which indicate to the user that he can 
cycle through choices, and serves to distinguish cycle items from text items: 

Category OsunView 
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Binary Choices 

An item that is either on or off may be created using either PANEL_TOGGLE, 
PANEL_CYCLE or PANEL_CH 0 ICE. The picture on the left below is a toggle, 
the two in the middle are cycles, and the one on the right is a choice: 

O' Grid Show Grid O Yes Grid O On Grid: B On Q Off 

Text Items 

Text items should have a colon after the label. 

For text items, it is recommended to have one or more buttons which cause the 
text item’s value to be acted on. In iconedit, for example, the user first enters 
a filename into the File: field, then presses the Load, Store, or Browse button in 
order to act on that filename. 

iconedit also allows the user to tvpe I Control-L 1.1 Control-S ). or (Control-B 1 
into the File: field as accelerators for the buttons. Use of such accelerators 
(including carriage return to mean “enter”) is not recommended, as it conflicts 
with future plans for the use of non-printable characters. 

For the sake of consistency, whenever a tool reads from and writes to a file, it 
should label these buttons with Load and Store. 

Allocation of Function 

Between Buttons and Menus 

Selecting a menu item is normally the same as either selecting a button or pick¬ 
ing from a choice item, bogglet ool(6), for example, has a menu for restart¬ 
ing the game (as well as other things) but has no buttons. Each of the four menu 
items could have been represented by a button instead, lif e(6) does not have a 
choice item, but rather lets you choose a starting pattern with a menu. Thus the 
question of when to use a button (or choice) and when to use a menu arises. Here 
are some rules of thumb: 

□ Items on the frame menu should not be duplicated as buttons, with the possi¬ 
ble exception of a Quit button (see next paragraph). 

□ Some tools typically run all the time, such as mailtool. Others are nor¬ 
mally invoked only long enough to do a job, such as iconedit. Tools in 
the second category, if they have any other buttons, should also have a Quit 
button. 

□ If a tool has a commit operation, then it may have a Done button, which is a 
combination of close 106 plus commit. Thus mailtool has a Done button. 

□ A tool should never have a Close button, since this operation is already 
available via both a menu and the keyboard. 

□ If a custom menu is provided, the menu items should not all be duplicated as 
panel items (buttons or choices), bogglet ool and lif e are examples of 
programs that have functionality in custom menus that are not duplicated as 
panel items. 

□ When a button and a menu item perform the same function, their labels 
should be identical. 

106 If the panel is in a subframe, the Done operation implies disappearing from the screen rather than 
closing, since subframes can’t become iconic. 
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B.5. Mouse Button Usage 


Allocation of Function 

Between Mouse Buttons 

Use of mouse buttons should be consistent with the rest of SunView. The left 
button should only be used to make selections. The right button should only be 
used to bring up menus. 107 

There is some discretion involved in the use of the middle button, however. In 
most of SunView, the middle button is used to adjust a selection. In text and 
shell windows, for example, the left button is used to mark the starting point of a 
selection, and the middle button is used to extend the selection. Similarly, in a 
pixel editor that allowed you to select regions, clicking the left button on a region 
could select just that region, and clicking the middle button on another region 
could add that region to the selection. On the other hand, in a tool that allowed 
you to move objects, the middle button could move an object, and 
(Control l-MIDDLE button could re-size it, which would be consistent with the 
way icons and frames are moved and re-sized. As a third alternative, in the 
iconedit drawing program the left button draws pixels (which is a kind of 
selecting) and the middle button erases. 

The best use of the middle button is still being discussed. Future versions of this 
guideline may specify more exactly how the middle button should be used. For 
now, the most common use is to extend the selection, and the next-most common 
is to move a graphic object. 

Using Mouse Buttons for 
Accelerators 

It is acceptable to use the mouse buttons as accelerators for common operations. 
The only caveat is that any accelerators should also be available from a menu or 
panel item. Thus in SunView clicking on a tool with the middle button moves 
the tool, but you can also move a tool using the frame menu. 

Some operations, on the other hand, cannot be invoked from a menu or panel 
button. In such cases the mouse is the only means of invoking the operation. For 
example, in iconedit you use the mouse for drawing, and the drawing opera¬ 
tions are not available from a menu or button. 

B.6. Cursors 

An application program should not do anything other than change the shape of 
the cursor when the cursor is moved into a new window, text edit presents a 
good example of using the cursor to alert the user that input is interpreted dif¬ 
ferently in different regions: The cursor is a thin diagonal arrow in the 
textsubwindow, a fat horizontal arrow in the scrollbar, and a diamond in the 
scrollbar buttons. 

B.7. Icons 

Tools should pack as much information as possible into their icons, clock and 
perf meter are examples of tools that make good use of icon real estate, tex- 
t edit is an example of a tool that could make better use of its icon. For exam¬ 
ple, it could contain a representation of the text being editing in a 1 point font. 
Small as that is, you can tell at a glance if you are editing C code or a mail mes¬ 
sage. 

107 People who want to hold the mouse with their left hand can put the “menu button** on the left and the 
“select button** on the right by setting the Left_Handed option in the Input category of def ault sedit. 
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Some icons, like the round face used by clock and the page with the protruding 
pencil used by text edit, have images with non-square outlines. These icons 
have the area outside of the image outline filled in with the root grey pattern so 
that the icons will blend in with the default SunView background. While this 
looks good when the background is in fact the default pattern, it is not recom¬ 
mended, since users can choose an arbitrary background pattern for SunView. 
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Converting SunWindows Programs to 

Sun View 

This appendix gives some guidelines for converting programs written using 
SunWindows to SunView. There are two classes of programs covered: those 
that create a tool and subwindows, and programs that call gf xsw_init () to 
take over an existing window or the console. 

Programs that fall outside these classes are probably UNIX-style programs that do 
not use windows at all. The conversion of such programs is in effect the subject 
of this whole manual. If you want to convert such a program to SunView, pay 
particular attention to Chapter 2, The SunView Model, and the specific discussion 
of Notifier interaction under Porting Programs to SunView in Chapter 17, The 
Notifier. You may also find some of the discussion later on in this appendix 
under Section C.2, Converting Gfxsubwindow-Based Code, helpful. 
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C.l. Converting Tools 

It is reasonably straightforward to convert tools that create windows in SunWin- 
dows to the SunView interface because they should already have the appropriate 
architecture. SunView programs, like Sun Windows programs, have three parts: 
initialization of static objects, starting up window system interaction, and the 
routines that are called after the tool is running in the window system. 

General Comments 

When porting to SunView, you should look through all of your code for Sun Win¬ 
dows function calls. If you see one, the odds are that you are going to have oth¬ 
ers. Look for every occurrence of the call and then change it to the new format. 
Since the SunView libraries are mixed in with the SunWindows libraries, you 
can mix the two types of functions calls, and not get any compilation errors. But 
you will get some inconsistent results. 

Programming Style Changes 


Object typedefs 

The capitalized typedefs for window system objects (applied to Panels, 
Panel_items and Panel_settings in 2.0 SunWindows) have been 
extended to nearly all SunView objects, including: 

Canvas Pixrect 

Cursor Pixwin 

Frame Rect 

Icon Rectlist 

Menu Scrollbar 

Panel Textsw 

Panel_item Tty 

Pixfont Window 

You should convert to using these data types in the interests of future compatibil¬ 
ity. See Object Handles in Chapter 3, Interface Outline, for more information on 
these types. 

Attribute Value Interface 

In SunView, the attribute value interface, introduced for panel subwindows in 2.0 
SunWindows, has been extended to all types of windows. Attributes for all win¬ 
dow types are set and obtained with the same two calls, window_set () and 
window_get(). 

All window types are created with the same call, window_create (). 

CAUTION 

The most frequently used SunView calls use attribute lists, and therefore 
must be null-terminated. SunView will only complain about a malformed 
attribute list at run time. 
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New Objects 


Canvas Subwindows 


Text Sub windows 


Scrollbars 


Most of the data types in the above list are objects new in SunView. Many 
objects in SunWindows correspond to objects in SunView, for example: 

tool => Frame 

ttysw => Tty 

Some objects such as the graphics subwindow and empty subwindow are not 
supported in SunView 108 . There are new objects that partially take their place. 

The canvas subwindow is a general-purpose drawing subwindow, which can 
replace gfx subwindows and empty subwindows. The size of the canvas you 
draw on need not be the same as the size of the window it is displayed in; you 
can create scrollbars to let the user adjust the visible part of the canvas. For a 
demonstration of the various canvas attributes, run the program 
/usr/demo/canvas_demo 

These allow for the display and editing of text in a scrollable window. The user 
can perform various actions on the text, including saving the text, searching in 
the text, and editing the text without the programmer having to deal with these 
interactions. 

Since there was no such window in SunWindows, your application may have had 
to use a gfx subwindow, a set of panel message items, or some strange technique 
involving tty sw_input () or piping to a tty subwindow to display text; the 
text subwindow can replace all these uses. 

Scrollbars can be attached to windows. In particular, the use of scrollbars with 
retained canvases makes it very easy to draw a fixed-size image without regard 
for window size changes. 


108 You can still compile and run code that uses these, but Sun does not intend to develop them further. 
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Objects in Common between 
SunView and Sun Windows 


Cursors 


Icons 


Cursors have changed. They are now type Cursor, and all calls relating to 
them have changed. Type Cursor should be looked at as a pointer to the struc¬ 
ture containing the cursor information. Here is how you would define a cursor: 
-- 

static short int help_bits [] = { 
tinclude "help.curs" 

}; 

mpr_static(help_pr, 16, 16, 1, help_bits); 

*_ J 


Once having created a cursor, you call window_set () to add it to a window, 
as in the following code fragment: 


Cursor help_cursor; 

main () 

{ 

/* make windows */ 
init cursor!); 


init_cursor() 

{ 

help_cursor = cursor_create(CURSOR_IMAGE, &help_pr, 

CURSOR_XHOT, 8, 
CURSOR_YHOT, 8, 
CURSOR_OP, XOR, 

0 ) ; 

window_set (window, WIN_CURSOR, help_cursor, 0); 


You now refer to all your cursors by the handle you get from 
cursor_create (). Cursors have their own create, destroy, copy, set, and get 
routines, as well as a number of attributes with no corresponding functionality in 
SunWindows. 


Icons have changed. They follow the same pattern as cursors; you define the 
data, create a pixrect, and then call icon_create () at run time. These also 
have their own create, destroy, set and get routines, although there are fewer attri¬ 
butes associated with them. 
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Menus 


Input Events 


The new walking menu package uses the attribute value interface. It has many 
more features than the old menu package. It does not support the stacking menu 
style of SunWindows. 109 

Menus also have their own routines and are created via function calls instead of 
being user-loaded data structures. They use the pointer type Menu for their han¬ 
dles instead of struct menuptr. One way to create them is to write a spe¬ 
cial menu_init () proc which loads them into their structures correctly. In 
your menu_init (), you have something like 


/ 



\ 


ml_items = menu_create( 




MENU_STRI NG__I TEM, 

"insert", 

INSERT, 


MENU_STRING_ITEM, 

"copy", 

COPY , 


MENU_STRING_ITEM, 

"replace", 

REPLACE, 


MENU_STRING_ITEM, 

"move" f 

XLATE , 


MENU_STRING__I TEM, 

"delete", 

DELETE, 


MENU_STRING_ITEM , 

"HELP", 

DRAW_HELP, 


0); 








Menu values from menu_get () ormenu_show () are returned as 
caddr_t’s. Be sure your types match. 

NOTE The old menu_display () and the newmenu_show () routines have a dif¬ 
ferent order for the arguments. 

The inputevent structure has not changed. However, you no longer have to 
generate events yourself in “selectedroutines via calls to 
input_readevent (). Instead, windows now have event handlers that are 
passed pointers to Event structures. 

There are a number of macros for making input events easier to deal with in Sun- 
View, so instead of having something like ie->ie_code you have 
event_id (ie), resulting in more readable code. 

Event types are not pointers, so you have to distinguish between 

Event *ie; 

and 

Event ie; 

in your code. You can use either, because the event functions don’t just manipu¬ 
late a handle as, for example, the cursor functions do. See Object Handles in 
Chapter 3, Interface Outline, for an explanation of when handles are pointers and 
when not. 


109 This is still available in the frame and root menus if you disable SunViewlWalking_Menus in 
defaultsedit. 
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Setting up Input Event Handling All the input events can be set up from the window_create () call or 

window_set () calls. Calls to win_*inputmask () are all replaced by 
these window_set () and window_create () calls. 

The distinction between “pick” and “keyboard” events is new in SunView, hav¬ 
ing been added to support the notion of a split input focus. 

CAUTION Be careful that when you are setting mouse events, you are modifying the 
WI N_*_P I CK_EVENT S and when you are setting keyboard events you 
modify WlN_*_KEYBOARD_EVENTS. You may get inconsistent results if 
you modify pick events on the keyboard mask. 


Sigwinch Handling Canvas event procedures no longer need all the gfx support for flag checking. 

Resize and repaint events are separately handled by the procedures you supply 
via the CANVAS_RESlZE_PROC and CANVAS_REPAlNT_PROC attributes. 
These procedures mean you should not try to catch sigwinch signals (and in fact, 
if you do, you will have problems; see below). 

Windows Making windows is very straightforward in SunView. Each window type has a 

handle — so instead of the inconsistent use of handles and fd’s to describe a 
window and manipulate it, you only use the window handle. You need to go 
through your code and update all the reference to the old tool_... handle types 
in the code. After you find them, locate all the function calls referring to them 
and update them to SunView window_set () and window_get () calls. 
Almost every window operation is supported by the attribute value interface; 
however, some low-level routines that are documented in the SunView 1 System 
Programmer’s Guide may still require window names or fd’s. 


window_get () is used to get an attribute of a window. It returns a caddr_t 
back to you, which must be cast into the appropriate type. So loading something 
into a rect struct would involve something like: 





\ 


Rect 

win size; 



Canvas 

canvas; 



canvas = 

: window_create( base_frame, CANVAS , 0); 



win_size 

:= *((Rect *)window_get(canvas, WIN_RECT)); 


V_ 





NOTE Be sure to cast values returned from get () routines to the correct type. 

The above * ( (Rect *)...) is needed otherwise you will get an ’incompatible 
type’ message from the compiler. 

Panels Most of the panel interface was already using an attribute value interface in 2.0 

SunWindows. panel_create () panel_set () and panel_get () should 
be changed to window_create (), window_set ( ) and window_get (). 

The PANEL_CU () macro was superseded by ATTR_COL ( ) and 
ATTR ROW(). 
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Signals 


Prompts 



If you are catching signals, then you should read the documentation on signals in 
Section 17.2, Restrictions, in the Notifier chapter. There are several that the 
Notifier now catches on your behalf. 

You should no longer be catching SIGWINCH signals. If you do, your program 
may never appear on the screen as it will start catching the signals and redrawing 
endlessly on die screen, which may not be visible. 

Instead of using the menu_prompt () facility of SunWindows, you should use 
the alerts package to prompt the user, or if necessary use pop-up subframes and 
window_loop (popup_f rame ) when prompting the user. The filer example 
programs in Chapter 4, Windows, uses the alerts package to implement a pop-up 
confirmer. 

menu_prompt () is documented here for completeness. The definitions used 
by menu_prompt () are: 

struct prompt { 

Rect prt_rect; 

Pixfont *prt_font; 
char *prt_text; 

} 

menu_prompt(prompt, event, windowfd) 
struct prompt *prompt? 

struct inputevent *event; 
int windowfd; 

menu_prompt () displays the string addressed by prompt->prt_t ext 
using the font prompt->prt_f ont. prompt->prt_rect is relative to 
windowfd. If either the r_width or the r_height fields of 
prompt->prt_rect has the value PROMPT_FLEXlBLE, that dimension is 
chosen to accommodate all the characters in prompt->prt_text. 

The fullscreen access method is used to display the prompt. After displaying the 
prompt, menu_prompt () waits for any input event other than mouse motion. 

It then removes the prompt, and returns the event which caused the return in 
event, windowfd is the file descriptor of the window from which input is 
taken while the prompt is up. 
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Table C-l SunWindows => SunView Equivalences 


In SunWindows 

In Sunview 

tool = tool_make() 

Frame frame = window_create (NULL, FRAME,..., 0); 

t o o l_pa r s e__a 11 

FRAME_ARGS or FRAME_ARGC_PTR_ARGV 
attributes to window__create (NULL, FRAME, ..., 0) 

tool__install () 
tool_select() 
tool_destroy() 

window_main_loop(frame); 

or, individually, 


tool_install () 

win_show attribute 

tool_select () 

window_main_loop(), notify_dispatch ( ) or notify_start () 

tool_destroy () 

window_destroy (basef rame) or window_don e (any window) 

signal (SIGWINCH, sigwinch) 

resize_proc and repaint_proc attribute 

TOOLSW_EXTENDTOEDGE 

WIN_EXTEND_TO_EDGE 

win grabioO 

WI N_GRAB_AL L_I NPUT attribute 

struct tool_io 

win_event_proc for window events. Other events, timers, etc. 
handled by individual calls to the Notifier to set up or interpose specific procs. 
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C.2. Converting Programs that run in gfxsubwindows are designed to take over an existing win- 

Gfxsubwindow-Based dow. In SunView you must create a tool for such programs to run in. One limi- 

Code tation of this approach is that the SunView version of the application must run 

under suntools; the old gf xsw_init () call would create a SunWindows 
environment if run on the “bare” Sun console. One major advantage gained by 
moving to SunView is that your code can use scrollbars. 


Basic Steps 


Replacing Tool Interaction 

Styles of Damage Checking 


o Include <suntool/sunview. h> and <suntool/canvas .h>. 

□ Remove all window-related #include statements; these will probably be 
included by sunview. h. 

□ Declare a Frame and a Canvas. 

□ Replace gf xsw_init () with calls to create the frame and canvas. 


Many gfx subwindow programs (and many of the Sun demos) call 
gf xsw_init () to take over a window, then run in a loop as they compute and 
draw an image in the gfx subwindow. At some point in the loop they check for 
damage to or alteration of the size of the gfx subwindow and handle it accord¬ 
ingly. 

In SunView, the coexistence of your program with the window system is less 
hidden from you. Read Chapter 2, The SunView Model, to understand how this 
coexistence works. In converting programs, you must ensure the Notifier runs at 
regular intervals so that window events such as close, quit, etc. are handled 
appropriately. 

Consult Chapter 17, The Notifier, for more information. 

You can either (1) set up your program so that, after initialization, control passes 
to the Notifier, which you have set up to call your imaging/computation routine 
periodically, or (2) let control continue to pass to your code, and change the pro¬ 
gram to call the Notifier at regular intervals. 


Either the Notifier Takes Over In the first case, you set up your imaging/computation routine as a function that 

is called when a timer expires. Do this by calling 

notif y_set_it imer_f unc (). If you want your imaging/computation rou¬ 
tine to blaze away non-stop (causing other programs to run more sluggishly), you 
request the timer function be called as soon as the Notifier has handled window 
events for you by giving the timer the special value 
&NOTIFY_POLLING_ITIMER. 

(void) notify_set_itimer_func(frame, my_animation, 

ITIMER_REAL, &NOTIFY_POLLING_ITIMER, ITIMER_NULL) ; 

V__ ) 


If your code sleep ()’s on a regular basis, then you should be able to modify it 
so that the Notifier calls your imaging/computation routine at the same interval. 
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The program spheres in Appendix A, Example Programs, is an example of this 
style of interaction. 

Or Your Code Stays in Control 

On the other hand, if your program just loops, perhaps while (—gf x_reps), 
then you could add to the loop a call to notif y_dispatch (). This will han¬ 
dle window system events and return. 

The program bounce in Appendix A, Example Programs, is an example of this 
style of interaction. 

If you do this then your program has to detect when the user has ‘Quit’ from the 
menu: see Finishing Up below. 

NOTE 

gf x_reps in a gfx subwindow program is set to a large number (200,000), but 
the user can change it through the command line argument 
-n numberofrepetitions. 

Handling Damage 

The Notifier will handle moving the window, resizing it, etc. However, resulting 
damage to your canvas may need to be repaired. In the gfx subwindow, 
GFX_DAMAGED is set whenever a SIGWINCH is received. In addition 
GFX_RESTART is set if the size of the window has changed or if the window is 
not retained. GFX_DAMAGED is set as a hint for you to call 
gf xsw_handlesigwinch (), which would clear up the damaged list and if 
the window was retained it would repaint the image for you. GFX_RES TART is 
set as a hint that the window had to be rebuilt, either because of damage and the 
window is not retained, or because of a resize. 

Many situations that you would need to handle yourself in a gfx subwindow are 
rendered superfluous by attributes of the canvas subwindow, such as 
CANVAS_AUTO_CLEAR, etc. For starters, canvases are retained by default; if 
your canvas has scrollbars and is retained, then you need not be concerned with 
resize events. Nevertheless, you may need to be aware when you must rebuild or 
repair your image. Read the Canvases chapter for more information. 

Rather than setting a flag, SunView calls your own procedure if you specify one 
with the CANVAS_REPAINT_PROC and CANVAS_RES IZE_PROC attributes. 
These are called with useful parameters for their tasks. 

You can modify your code so that the repair activity that used to take place after 
noticing the flags have been set now takes place in the procs themselves, or you 
can write the procs so they set flags similar to the GFX_RE START and 
GFX_REPAINT flags and return, and leave your repair code almost untouched. 
Or, depending on your application, you can set up your canvas so that the win¬ 
dow system handles all damage. 

The gfxsw Structure 

The gfxsw structure has fields in it that carry useful information. Comparable 
information is available in SunView, so you can declare and setup a comparable 
structure in SunView. The bounce program in Appendix A, Example Programs, 
does this. 

Gfx subwindow-based programs use the gf x->gf xsw_rect to determine the 
geometry of the window they are drawing in. Since the starting point of this was 
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Miscellaneous 


relative to the gfxsw, it was always O. 110 In SunView the width and height of the 
canvas you draw in are available through the canvas attributes CANVAS_WIDTH 
and CANVAS_HEIGHT. The fields of the gf x->gfxsw_rect correspond to 
these attributes as follows: 

coord r_left, r_top; are both = 0 

short r_width, r_height; are the CANVAS_WIDTH and 

CANVAS_HEIGHT attributes. 

As described above, you can use your own GFX_RESTART and GFX_REPAINT 
flags. 

If you care about the gfxsw command line arguments, insert code into your 
program’s argv, argc parsing loop to handle the gfx options that used to be 
taken care of for you. The bounce program has reasonable code to do this. 

If your imaging routine is in control and periodically calls the Notifier, then when 
the window is quit your routine must know that this has occurred. Otherwise, the 
imaging routine will continue to draw in a window that has been destroyed, and 
you will see error messages like 

(~ ; : : - : ' —— " - ~~ i 

WIN ioctl number C0146720: Bad file number 

_____ : ____ J 

until you kill the program. 

What you must do is interpose in front of the frame’s destroy event handler so 
that your program will know when the frame goes away. See the item on Getting 
Out in Porting Programs to SunView in the Notifier chapter. 

If your program exits on its own, then it can call window_done () to destroy 
its windows. This will invoke your interposed notice-destroy routine (which may 
or may not matter depending on what it does). It will also call the standard 

Are you sure you want to Quit? 

alert unless you set FRAME_NO_CONFIRM. 

gf xsw_getretained () is equivalent to the CANVAS_RETAINED attribute. 
Canvases are retained by default. 

gf xsw_init () doesn’t consume the gfxsw command line options -r, 

-n Number_of repetitions, etc; your code may do strange things with its argu¬ 
ments to deal with this. 



no 


Many of the demos supplied by Sun are confused on this point and go through unnecessary steps. 
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Two Examples Listings of two programs converted from SunView are in Appendix A, Example 

Programs. 

bounce The first is a new version of bouncedemo(6). It now draws its bouncing square 

in a canvas. It has code to parse the standard gfx subwindow command line 
arguments. It preserves the original while (gfx->gfx_reps) {...} loop 
structure of bouncedemo by calling not i fy_di spat ch () at the top of the 
loop. Because it is running in a loop it must detect when the user has ‘Quit’ the 
window, so it interposes before its frame’s destroy routine using 
not if y_interpose_destroy_f unc (). The routine that is called just 
sets a flag so the program knows to exit from the loop. 

spheres The second is a version of spheresdemo(6). It now draws its shaded spheres 

in a canvas with scrollbars, so you can see all the image in a small window. It 
handles the notification of SunView events by asking the Notifier to call the 

drawing routine (my_animation ()) as often as possible, using 
. — ---. 

(void) notify_set_itimer_func(frame, my_animation, 

ITIMERJREAL, & NOTIFY_POLLING_ITIMER, ITIMER_NULL); 

\_ j 

Since the drawing operation is under the control of the Notifier, the Notifier can 
control the program, so the while (gfx->gfx_reps) {...} loop structure 
is replaced by a call to window_main_loop (); this will terminate the pro¬ 
gram when the user chooses ‘Quit’ from the frame menu. 

spheres detects when it is made iconic by interposing in front of the frame’s 
client event handler using not if y_interpose_event_func (). The rou¬ 
tine that is called calls the normal event_f unc, then checks to see if the frame 
has changed state: if it has been closed it turns the notify timer off altogether, so 
the drawing routine is no longer called; if it has been opened the timer is set back 
to immediate polling. 

bounce should do this also — there is little point in drawing when iconic unless 
you are drawing a single compute-intensive image. 


Detecting when the Program is 
Iconic 
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action procedure for menu item, 229 
alarm(3), 285 
alert, 199 

arrow, 201 

beeping, 202 

buttons, 201 

components of, 201 

controlling beeping, 208 

creation, 202 

described, 199 

example program, 389 

interface summary, 316 

messages and simple buttons, 203 

position of, 202 

table of attributes, 316 

table of functions, 318 

text message, 201 

types of buttons, 204 

use with blocking pop-ups, 47 

uses of, 201 

using trigger events, 206 
alert attributes, 316 

ALERT_BUTTON, 316 
ALERTJBUTTON_FONT, 316 
ALERT_BUTTON_NO, 204, 316 
ALERT_BUTTON_YES, 204, 316 
ALERT_MES S AGE_, 203 
ALERT_MESSAGE_FONT, 316 
ALERT_ME S SAGE_STR I NGS, 316 
ALERT_MESSAGE_STRINGS_ARRAY_PTR, 316 
ALERT_NO_BEEP ING, 208, 316 
ALERT__OP T I ONAL, 317 
ALERT__P OS IT I ON, 317 
ALERTJTRIGGER, 207, 317 
alert functions, 318 

alert_prompt (), 202, 318 
possible status values, 202 
ASCH events, 86 

asynchronous signal notification, 293 
ATTR__COL, 54, 160, 309 
ATTR_COLS, 310 
ATTR__LIST, 311 
ATTR_ROW, 54, 160, 309 
ATTR_ROWS, 310 
attribute functions 

attr create_list (),310 


attribute lists 

creating reusable lists, 310 
default attributes, 311 
maximum size, 29, 311 
overview, 28 
utilities, 309 
attribute ordering, 55 
for canvases, 69 
in text subwindow, 132 

B 

base frame, 16 
boundary manager, 19 
button image constructor, 168 
button panel item, 158, 167 thru 169 
buttons with menus, 168 

c 

callback procs, 20 

callback style of programming, 20 

canvas, 61 

attribute order, 69 
automatic sizing, 69 
backing pixrect, 66 

canvas space vs. window space, 70, 98 

color in canvases, 72 

coordinate system, 65 

default input mask, 70 

definition of, 61 

handling input, 70 

interface summary, 319 

model, 65 

monochrome in multiple plane groups, 125 
non-retained, 66 
pixwin, 63, 65 
repaint procedure, 66 
repainting, 66 
resize procedure, 67 
retained, 66 
scrolling, 64 
table of attributes, 319 
table of functions and macros, 320 
tracking changes in size, 67 
writing your own event procedure, 70 
canvas attributes, 319 

CANVAS__AUTO__CLEAR, 66, 319 
CANVAS__AUTO_EXPAND, 69, 319 
CANVAS AUTO_SHRINK, 69, 319 
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canvas attributes, continued 

CANVA S__FA S T_MON0, 319 
CANVAS_F I XED_I MAGE, 67, 319 
CANVAS__HE IGHT, 65, 319 
CANVAS_MARGIN, 65, 319 
CANVASJPIXWIN, 65, 103, 319 
CANVAS_REPAINT_PROC, 66, 319 
CANVAS_RESIZE_PROC, 319 
CANVAS_RE TAI NED, 66, 319 
CANVAS__WIDTH, 65, 69, 319 
canvas functions and macros, 320 
canvas_event (), 71, 98, 320 
canvas_pixwin (), 63, 65, 103, 320 
canvas_window_event (), 70, 320 
CAP SMASH, 96, 97 
character unit macros 

ATTR_COL, 54, 160, 309 
ATTR_COLS, 310 
ATTR_ROW, 54, 160, 309 
ATTR_ROWS, 310 

child process control using the Notifier, 288 

choice panel item, 158,170 thru 176 

classes of windows, 16 

client handle used by the Notifier, 287 

clipping in a pixwin, 112 

code examples, see example programs 

color, 113 

advanced colormap manipulation example program, 441 

animation, 122, 447 

background color of pixwin, 115 

color during fullscreen access, 119 

colormap, 113 

colormap access, 118 

colormap segment, 114 

cursors and menus, 119 

default colormap segment, 115 

determining if display is color, 119 

example programs, 441 

fast color change, 114 

foreground color of pixwin, 115 

FRAME_BACKGROUND_COLOR, 115 

FRAME_F OREGROUND_COLOR, 115 

FRAME_INHERIT_COLORS, 115 

grayscale compatibility, 120 

hardware double-buffering, 122 

in canvases, 72 

introduction, 113 

one colormap segment per window, 116 
showcolor , 116 

software double-buffering, 120,122 
software double-buffering example program, 447 
table of color functions, 360 
using color, 119 

compiling SunView programs, 27 
confirmation 

FRAME_N0_C0NF IRM, 382 
control structure in Notifier-based programs, 21 
converting existing programs to use the Notifier, 303 
converting programs to SunView 
attribute-value interface, 478 
cursors, 480 

equivalent SunWindows routines, 484 


converting programs to SunView, continued 
gfx subwindow-based, 485 
gfx subwindow-based examples, 454 
icons, 480 
input events, 481 
menus, 481 
new objects, 479 

non-window based programs, 477 
panels, 482 
prompts, 483 
signals, 483 

SunWindows-based, 477 
typedefs, 478 
windows, 482 

write a prompt. .. read a reply , 216 
CTRLMASK, 96, 97 
cursor, 253 

crosshair border gravity, 258 
crosshair gap, 258 
crosshair length, 258 
crosshairs, 256 
definition of, 253 
fullscreen crosshairs, 258 
hot spot, 257 
interface summary, 321 
rasterop, 257 

setting position of mouse cursor, 91 
table of attributes, 321 
table of functions, 323 
cursor attributes, 321 

CURSOR_CROSSHAIR_BORDER_GRAVITY, 258, 321 
CURSOR__CROSSHAIR_COLOR, 321 
C UR S OR__CROS SH AI R_G AP , 258, 321 
CURSOR__CROSSHAIR_LENGTH, 258 
CURSOR_CROSSHAIR_OP, 321 
CURSOR_CROSSHAIR__THICKNESS, 321 
CURSOR_FULLSCREEN, 258, 321 
CURSOR_HORIZ_HAIR_BORDER_GRAVITY, 321 
CURSOR_HORIZ_HAIR_COLOR, 321 
CURSOR_HORIZ_HAIR_GAP, 321 
CURSOR_HORIZ_HAIR_OP, 321 
CURSOR_HORIZ_HAIR_THICKNESS, 321 
CURSOR_I MAGE, 256, 257, 321 
CURSOR_OP, 257, 321 
CURSOR_SHOW_CROSSHAIRS, 321 
CURSOR_SHOW_CURSOR, 321 
CURSOR__SHOW_HORI Z_HAIR, 321 
C UR S OR_S HOW_VERT__H AIR, 321 
CURSOR__VERT__HAIR__BORDER_GRAVITY, 322 
CURSOR_VERT_HAIR_COLOR, 322 
C URSOR__VERT_H AI R_GAP , 322 
CUR S OR_VERT_H AI R_OP , 322 
CURSOR_VERT_HAIR_THICKNESS , 322 
CURSOR_XHOT, 257, 322 
CURSOR_YHOT, 257, 322 
cursor constants 

CURSOR_TO_EDGE, 258 
cursor functions, 323 

cursor_copy (), 255, 323 
cursor_create (), 255, 323 
cursor_destroy (), 255, 323 
cursor_get (), 255, 323 
cursor_set (), 255, 323 
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CURSOR_TO_EDGE, 258 
cycle panel item, 174 

D 

data types, 324 
caddr_t, 28 
object handles, 28 
opaque, 28 

default colormap segment, 115 

default system font, 41 

DEFINE_ICON__FROM_IMAGE (), 40, 262 

DE STROY_CHECKING, 300 

DESTROY_CLEANUP, 300 

DE STROY_PROCES S_DEATH, 300 

destroying windows 

FRAME_N0_CONFIRM, 382 
destruction of objects, 300 
disable Quit confirmation 

FRAME_NO_CONFIRM, 41, 382 
dispatching events 

calling the Notifier explicitly, 303 
calling the Notifier implicitly, 303 
display 

batching, 110 

canvases and gfxsw’s in multiple plane groups, 125 
determining if in color, 119 
enable plane, 124 
locking, 109 

locking and batching interaction, 112 
overlay plane, 124 
plane group, 124 
software double-buffering, 120 
speed, 108 

distribution of input in a window, 90 

E 

event 

ASCD event codes, 86 

canvas space vs. window space, 70, 98 

definition of, 80 

function key event codes, 88 

keyboard focus event codes, 88 

META event codes, 86 

mouse button event codes, 86 

mouse motion event codes, 86 

panel space vs. window space, 193 

reading events explicitly, 97 

relationship to Notifier, 20 

repaint and resize event codes, 87 

shift key event codes, 89 

timeout, 294 

using an event with alerts, 206 
window entry and window exit event codes, 87 
event codes, 330, 82 
BUT (),86 
KBD_DONE, 88 
KBD_REQUEST, 88 
KBD_USE, 88 
KEY_LEFT, 88 
KEY_RIGHT, 88 
KEYJTOP, 88 
LOC DRAG, 70, 86 


event codes, continued 
LOC__MOVE, 86 
LOC_RGNENTER, 87 
LOC_RGNEX IT, 87 
LOC_STILL, 86 
LOC_TRAJECTORY, 86 
LOC_WINENTER, 87 
LOC_W INEXIT, 87 
MS_LEFT, 86 
MS_MIDDLE, 86 
MS_RI GHT, 86 

PANEL_EVENT_CANCEL, 190 
PANEL_EVENT_DRAG_IN, 190 
PANEL_EVENT_MOVE_IN, 190 
SCROLL__REQUEST, 80 
SHIFT_CAPSLOCK, 89 
SHIFT_CTRL, 89 
SHIFT_LEFT, 89 
SHIFT_LOCK, 89 
SHIFT_META, 89 
SHIFT_RIGHT, 89 
WIN_REPAINT, 70, 87 
WIN_RESIZE, 70, 87, 299 
WIN_STOP, 88 
event descriptors, 333 

WI N_ASC 11_E VENT S, 70, 90, 333 
WIN_IN__TRANSI T_EVENTS, 90, 333 
WIN_MOUSE_BUTTONS, 90, 333 
WIN_NO_EVENTS, 90, 333 
WIN_UP_ASCII_EVENTS, 90, 333 
WI N_UP_EVENTS, 90, 333 
event handling 

at the Notifier level, 288 
in canvases, 70 
in panels, 189 
event procedure 
form of, 81 

writing your own for a canvas, 70 
writing your own for a panel item, 191 
event state retrieval macros 
event_action (), 96 
event_ctrl_is__down (), 96 
event_is_ascii (), 96 
event_is__button (), 96 
event_i s_down (), 96 
event_is_key_lef t (), 96 
event__is_key_right (), 96 
event_is_key_top (), 96 
event_is_meta 0,96 
event_is_up (), 96 
event_meta_is_down (), 96 
event_shift_is_down (), 96 
event_shiftmask (), 96 
event_time (), 96 
event_x (), 96 
event_y (), 96 
event state setting macros 

event_set_down (), 97 
event_set__id (), 97 
event_set_shiftmask (), 97 
event__set_time (), 97 
event_set_up (), 97 
event_set_x (), 97 
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event state setting macros, continued 
event_set_y (), 97 
event stream, 80 
example programs, 389 
animatecolor , 122,447 
bounce , 454 
color manipulation, 441 
color edit, 118,441 
colormap manipulation, 441 
converting terminal-based programs, 216 
creating menus, 416 
detool , 430 

discussion of image browser_1 program, 50 
discussion of image browser2, 53 
discussion of simple file manager, 44 
filer , 44,389 
fontjnenu , 416 

gfx subwindow-based demos converted to SunView, 454 

gfxsw_init to SunView, 454,461 

image browser_1, 401 

image browser_2, 406 

list files in tty subwindow, 42 

minimal SunView program, 37 

notify_dispatch (), 216,454 

notify__set__itimer_func (), 461 

resize_demo, 52, 299,425 

row/column space in a window, 406 

show color, 116 

simple file manager, 389 

simple panel window, 39 

spheres, 461 

sub window layout, 401 

tty subwindow escape sequences, 412 

tty subwindow I/O, 412 

tty jo, 412 

typein, 437 

F 

f cntl(2), 286,290 
file descriptor usage, 57 
filer , 44 

flow of control in Notifier-based programs, 21 
font functions 

pf_default (),41,106 
pf_open (),41 
frame 

command line frame attributes, 386 
definition of, 16 
fitting around subwindows, 41 
frame header, 18 

layout of subwindows within a frame, 51,52, 299,425 
menus, 18 

modifying destruction using the Notifier, 299 
modifying open/close using the Notifier, 297 
table of attributes, 382 
frame attributes, 382 

FRAME_ARGC_PTR_ARGV, 40, 382 
FRAME_ARGS, 55, 382 
FRAME_BACKGROUND_COLOR, 115,382 
FRAME_CLOSED, 382 
FRAME_CLOSED_RECT, 382 
FRAME_CMDLINE_HELP_PROC, 382 
FRAME CURRENT RECT, 382 


frame attributes, continued 

FRAME_DEFAULT_DONE_PROC, 382 
FRAME_DONE_PROC, 382 
FRAME_EMBOLDEN_LABEL, 382 
FRAME_FOREGROUND_COLOR, 115, 382 
FRAME_ICON, 40,382 
FRAME_INHERIT_COLORS, 115, 382 
FRAME_LABEL, 40, 382 
FRAME_NO_CONFIRM, 41, 382 
FRAME_NTH_SUBFRAME, 383 
FRAME_NTH_SUBWINDOW, 383 
FRAME_NTH_WINDOW, 383 
FRAME_OPEN_RECT, 383 
FRAME_SHOW_LABEL, 40, 45, 383 
FRAME_SUBWINDOWS_ADJUSTABLE, 383 
free(3), 311 
function keys, 88 

G 

generate procedure 
for menu, 244 
for menu item, 243 
for pull-right, 246 

generate procedure operation parameter values 
MENU_DISPLAY, 242 
MENU_DISPLAY_DONE, 242 
MENU_NOTIFY, 242 
MENU_NOTIFY_DONE, 242 
getitimer(2), 285 
gfx subwindow 

pw_use_f ast_monochrome (), 125 
converted demo programs, 454, 461 
converting to SunView, 485 
demo programs converted to SunView, 454 
monochrome in multiple plane groups, 125 

H 

header files 

overview, 27 

<suntool/canvas.h>, 61 
<suntool/icon .h>, 261 
< suntool/menu .h>, 221 
<suntool/panel.h>, 153 
<suntool/scrollbar .h>, 165,267 
<suntool/seln .h>, 279 
<suntool/sunview.h>, 27 
<suntool/textsw.h>, 129 
<suntool/tty .h>, 211 
<sunwindow/attr.h>, 311 
<sunwindow/cms_mono.h>, 115 
<sunwindow/pixwin.h>, 101 
<sunwindow/rect.h>, 52 
<sunwindow/win_cursor.h>, 253 
<sunwindow/win_input.h>, 77 
<sunwindow/window_hs. h>, 77, 101 

i 

icon, 261 

definition of, 19 

interactive editor for icon images, 262 
interface summary, 328 
Loading Icon Images At Run Time, 263 
modifying the icon’s image, 263 
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icon, continued 

table of attributes, 328 
table of functions and macros, 329 
icon attributes, 328 
ICON_FONT, 328 
I CON_HE IGHT, 328 
ICON__IMAGE, 328 
I CON_I MAGE_RECT, 328 
ICON_LABEL, 328 
I CON_LABEL__RECT, 328 
ICON_WIDTH, 328 
icon functions and macros, 329 

DEFINE_ICON_FROM_IMAGE (), 40, 262,329 
icon__create (), 262, 329 
icon_destroy (), 329 
icon_get (), 329 
icon_set () , 329 
image browser _1 , 50 
image browser _2, 53 
images 

in icons, 262 
in menus, 227 
mpr_static (), 227, 262 
using images generated with iconedit, 227, 262 
include files — see “header files”, 27 
initiating event processing, 35 
input, 77 

ASCD events, 90, 333 
designee, 92 
environment, 79 
event descriptors, 90 
event macros, 96, 97 
flow of control, 97 
focus, 91 
focus control, 91 
grabbing all input, 92 
in canvases, 70 
interface summary, 330 
keyboard focus, 88, 91 
keyboard mask, 91 
mask, 91 thru 95 
mouse motion, 86 
pick focus, 91 
pick mask, 91 
reading, 97 
recipient, 92 

refusing the keyboard focus, 88 
releasing, 92 
shift state, 97 
state, 96 

table of event codes, 82, 330 
table of event descriptors, 333 
table of input-related window attributes, 334 
Virtual User Input Device ( VUID ), 80 
input event codes 

SCROLL_REQUEST, 83, 331 
interposition, 287, 296 thru 302 
interval timers, 294 thru 296 
ioctl(2), 286 
it_interval struct, 296 


K 

KBD__DONE, 88 
KBD_REQUE ST, 88 
KBD_USE, 88 
KEY_LEFT, 88 
KEY_RIGHT, 88 
KEYJTOP, 88 
keyboard focus, 88 

L 

layout of items within a panel, 160 

layout of subwindows within a frame, 51 

libraries used in SunView, 27 

LOC_DRAG, 86 

LOC_MOVE, 86 

LOC_RGNENTER, 87 

LOC_RGNEXIT, 87 

LOC_STILL, 86 

LOCJTRAJECTORY, 86 

LOCJfINENTER, 87 

LOC_WINEXIT, 87 

locator, see mouse 

locator motion event codes, 86 

M 

Menu, 327 
menu 

attributes to add pre-existing menu items, 235 

basic usage, 224 

callback procedures, 240 

client data, 228 

default selection, 249 

destruction, 238 

display stage of menu processing, 241 

example program, 416 

for panel items, 158 

generate procedure, 242 

inactive items, 231 

initial selection, 249 

interface summary, 335 

notification stage of menu processing, 242 

notify procedure, 228, 247 

pull-right, 221 

searching for a menu item, 239 
shadow, 228 
table of attributes, 335 
table of functions, 341 
table of menu item attributes, 339 
user customizable attributes, 250 
walking, 221 
menu attributes, 335 

MENU_ACT ION_IMAGE, 237, 335, 339 
MENU_ACTI ON_ITEM, 237, 335, 339 
MENU_ACTION_PROC, 339 
MENU_APPEND_I TEM, 235, 335, 339 
MENU_BOXED, 231, 250, 335, 339 
MENU_CENTER, 335, 339 
MENU_CLIENT_DATA, 228, 335, 339 
MENU__COLUMN_MAJOR, 335 
MENU_DEFAULT, 335 
MENU DEFAULT_ITEM, 249, 335 
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menu attributes, continued 

MENU_DEFAULT_SELECT I ON, 249,250,335 
MENU_DESCEND_F IRST, 239, 335 
MENO_FEEDBACK, 234, 339 
MENU_FIRST_EVENT, 335 
MENU_FONT, 228,233, 250, 335,339 
MENO_GEN_PROC, 242, 243, 244, 335, 339 
MENU_GEN_PROC_IMAGE, 339 
MENU_GEN_PROC_ITEM, 242, 339 
MENU_GEN_PULLRIGHT, 246, 339 
MENO_GEN_PULLRIGHT_IMAGE, 237, 246, 335, 339 
MENU_GEN_PULLRIGHT_ITEM, 237, 246, 335, 339 
MENO_IMAGE, 339 

MENU_IMAGE_ITEM, 225, 229, 237, 336, 339 
MENU_IMAGES, 227, 237, 336 
MENU_INACTIVE, 231, 339 
MENU_INITIAL_SELECTION, 249, 250, 336 
MENU_INITIAL_SELECTION_EXPANDED, 250, 336 
MENU_INITIAL_SELECTION_SELECTED, 250, 336 
MENU_INSERT, 234, 235, 336 
MENU_INSERT_I TEM, 235, 336 
MENO_INVERT, 340 
MENU_ITEM, 226,233, 237,336 
MENU_JUMP_AFTER_NO_SELECTION, 250, 336 
MENU_JUMP_AFTER_SELECT I ON, 250, 336 
MENU_LAST_EVENT, 336 
MENU_LEFT_MARGIN, 230, 250, 336, 340 
MENU_MARG I N, 230, 231, 250, 336, 340 
MENU_NCOLS, 231, 336 
MENU_NI TEMS, 233, 336 
MENU_NOT I FY_PROC, 337 
MENU_NROWS, 231, 336 
MENU_NTH_ITEM, 233, 337 
MENU_PARENT, 337, 340 
MENU_PULLRIGHT, 226,233, 340 
MENU_PULLRIGHT_DELTA, 250, 337 
MENU_PULLRIGHT_IMAGE, 237, 337, 340 
MENU_PULLRIGHT_ITEM, 236,237,337, 340 
MENU_RELEASE, 234, 238, 340 
MENU_RELEASE_I MAGE, 340 
MENU_REMOVE, 235, 337 
MENU_REMOVE_ITEM, 235, 337 
MENO_REPLACE, 235, 337 
MENU_REPLACE_ITEM, 235,337 
MENU_RIGHT_MARGIN, 230,250, 337,340 
MENU_SELECTED, 337, 340 
MENU_SELECTED_ITEM, 249, 337 
MENU_SHADOW, 228,232,250, 337 
MENU_STAY_UP, 337 
MENU_STRING, 226,233,340 
MENU_STRING_ITEM, 225, 229, 237, 337, 340 
MENU_STRINGS, 237, 337 
MENU_TITLE_IMAGE, 228, 338 
MENU_TITLE_ITEM, 228, 338 
MENUJTYPE, 338,340 
MENU_VALID_RESULT, 338 
MENU_VALUE, 225, 229, 340 
menu callback procedures 
generate procedures, 242 
notify and action procedures, 247 
menu data types 
Menu, 327 

Menu_generate, 242, 327 
Menu item, 327 


menu functions, 341 

menu_create (), 224, 341 
menu_create_item (), 234, 341 
menu_destroy (), 238, 341 
menu_destroy_with_proc (), 238, 341 
menu_find (), 239, 341 
menu_get (), 224, 341 
menu_return_item (), 342 
menu_return_value (), 342 
menu_set (), 224, 341 
menu_show (), 224, 229,240, 244, 341 
menu_show_using_fd (), 342 
menu item 

action procedure, 229,247 
generate procedure, 229 
margins, 230 
table of attributes, 339 
value of, 229 

menu package, 221 thru 251 
menu processing 

display stage, 240 
notification stage, 240 
MENU_DISPLAY, 242 
MENU_DISPLAY_DONE, 242 
Menu_generate, 242, 327 
Menu_item, 327 
MENU_NOTIFY, 242 
MENU_NOTIFY_DONE, 242 
menu_prompt (), 483 
message panel item, 158,167 
META events, 86 
META_SHIFT_MASK, 96, 97 
mouse 

event codes for mouse buttons, 86 
setting position of mouse cursor, 91 
tracking, 86 

mpr_static (), 227, 262 
MS_LEFT, 86 
MS_MIDDLE, 86 
MS_RIGHT, 86 

multiple views in text subwindows, 147 

N 

namespaces reserved by Sun View, 30 
Notifier 

asynchronous signal notification, 293 
base event handler, 296 
child process control events, 288 
client handle, 287 

converting existing programs to use the Notifier, 303 
debugging, 306 

discarding the default action, 299 

error handling, 305 

event handler function, 287 

flow of control in Notifier-based programs, 21 

interposing on frame open/close, 297 

interposing on resize events, 299, 425 

interposition, 287 

overview, 20, 287 

pipes, 290 

polling, 295 
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Notifier, continued 

prohibited signals, 286 
prohibited system calls, 285 
registering an event handler, 288 
restrictions imposed on clients, 285 
signal events, 291 
table of functions, 343 
when to use, 285 
Notifier functions, 343 

notify__default__wait3 (), 288,343 
notify_dispatch (), 303,343 
not ify_do_di spat ch (), 216, 304, 343 
not if y_dump (), 306 

notify_interpose_destroy_func (), 299, 343 
notify_interpose_event_func (), 297, 343 
notify_interpose_wait3_func (), 215 
notify_itimer_value (), 285, 296, 343 
notify_next_destroy_func (), 343 
notify__next_event_func (), 297, 344 
not ify_no__di spat ch (), 304, 344 
notify_perror (), 305, 344 
notify_set_destroy_func (), 286, 344 
notify_set_exception_func (), 286, 344 
notify_set__input_func (), 286, 290, 292, 344 
notify__set_itimer_func (), 285, 294, 295, 296,344 
notify__set_output__func (), 286, 292, 345 
notify_set_signal_func (), 88,287, 291, 345 
notify_set__wait3_func (), 286, 288, 345 
not if y_start (), 345 
notify__stop (), 304, 345 
notify__veto_destroy (), 300, 345 
notify procedure 
for menu, 228 
for panel button items, 167 
for panel choice items, 172 
for panel slider items, 184 
for panel text items, 180 
for panel toggle items, 176 
notify procs, 20 

NOTIFYJDONE, 288, 289, 290, 295, 300, 302 
notify__errno, 305 
Notify_error, 305 
NOT I FY_ERROR__ABORT, 306 
NOTIFY_FUNC_NULL, 291, 305 
N0TIFY_IGN0RED, 288, 289, 293 
NOTIFY_OK, 305 
NOTIFY_POLLING_ITIMER, 295 

o 

object 

definition of, 9 
destruction of, 300 
handle, 28 

non-window visual objects, 11 
window objects, 11 
opening a font, 41 

p 

painting panels and panel items, 185 
panel, 153,327 

action functions, 190 
attributes, 346 


panel, continued 

attributes applying to all item types, 160 

caret, 179 

caret item, 179 

caret manipulation, 180 

creation, 159 

data types, 327 

default event-to-action mapping, 189 

definition of, 158 

event handling mechanism, 189 

interface summary, 346 

item label, 158 

item menu, 158 

iterating over all items in a panel, 188 
modifying attributes, 162 
painting, 185 

panel space vs. window space, 193 
panel-wide item attributes, 163 
positioning items within a panel, 160 
retrieving attributes, 163 
simple panel window example, 39 
table of attributes, 346 
table of functions and macros, 353 
table of generic panel item attributes, 347 
using scrollbars with, 165 
panel attribute settings 

PANEL_ALL, 170,176, 180, 184 
PANEL_CLEAR, 185 
PANEL_CURRENT, 170 
PANEL_DONE, 184 
PANEL_HORI ZONTAL, 162,178 
P ANEL_I NVERTE D, 172 
PANEL_MARKED, 172 
PANEL_NO_CLEAR, 185 
PANEL_NON_PRINTABLE, 180 
PANEL_NONE, 170, 172, 176,180, 185 
PANEL_SPECIFIED, 180 
PANEL_VERT I CAL, 162, 170,178 
panel attributes, 346 

PANEL_ACCEPT_KEYSTROKE, 189, 190, 346, 347 
PANEL_BACKGROUND_PROC, 189,190, 346 
PANEL_BLINK_CARET, 164, 346 
PANEL_BUTTON, 160 
PANEL_CARET_I TEM, 162,179,346 
PANEL_CHOICE, 160 
PANEL_CHOICE_FONTS, 349 
PANEL_CHOICE_IMAGE, 164, 349 
PANEL_CHOICE_IMAGES, 170, 349 
PANEL_CHOICE_STRING, 349 
PANEL_CHOICE_STRINGS, 170, 349 
PANEL_CHO I CE_X, 349 
PANEL_CHOICE_XS, 170, 349 
PANEL_CHO I CE_Y, 349 
PANEL_CHO I CE_YS, 349 
PANEL_CHOICE_YS ,, 170 
PANEL_CHOICES_BOLD, 349 
PANEL_CLIENT_DATA, 188, 347 
PANEL_CYCLE, 160 

PANEL_DISPLAY_LEVEL, 170, 176, 349 
PANEL_EVENT_PROC, 189,191, 346, 347 
PANEL_FEEDBACK, 172, 349 
PANEL_FIRST_ITEM, 188, 346 
PANEL_ITEM_RECT, 347 
PANEL ITEM_X, 160, 347 
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panel attributes, continued 

PANEL_ITEM_X_GAP, 161, 346 
PANEL_ITEM_Y, 160, 347 
PANEL_ITEM_Y_GAP, 161, 346 
PANEL_LABEL_BOLD, 163, 346, 347 
PANEL_LABEL_FONT, 347 
PANE L_L ABE L_ I MAGE, 167, 347 
PANEL_LABEL_STRING, 167, 347 
PANEL_LABEL_X, 162, 347 
PANEL_LABEL__Y, 162, 347 
PANEL_LAYOUT, 162, 163, 170, 178, 346, 347, 349 
P ANEL_MARK__I MAGE, 349 
PANEL_MARK_I MAGES, 170, 350 
PANEL_MARK_X, 350 
PANEL_MARK__XS, 170, 350 
PANEL_MARK_Y, 350 
PANEL_MARK_YS, 170, 350 
PANEL_MASK_CHAR, 352 
PANEL_MAX_VALUE, 184, 185, 351 
PANE L_MEN U_CHO I CE_F ONT S, 347 
PANEL_MENU__CHOICE_IMAGES, 347 
PANEL_MENU_CHOICE_STRINGS, 183, 347 
PANEL_MENU_CHOI CE_VALUES, 183, 348 
PANEL_MENU_MARK_I MAGE, 178, 350 
PANEL_MENU_NOMARK_I MAGE, 178, 350 
PANEL__MENU_TITLE_FONT, 348 
PANEL_MENU__T ITLE__IMAGE, 348 
PANEL_MENU_TITLE_STRING, 348 
P ANEL_ME S SAGE, 160 
PANEL_MIN_VALUE, 184, 185, 351 
PANEL_NEXT_ITEM, 188, 348 
PANEL_NOMARK_IMAGE, 350 
PANEL_NOMARK_IMAGES, 170, 350 
PANEL_NOTIFY_LEVEL, 180, 184, 351, 352 
PANEL_NOTIFY_PROC, 167,172, 180, 348 
PANEL_NOTIFY_STRING, 180, 352 
PANEL_PAI NT, 163, 185, 348 
PANEL_PARENT_PANEL, 348 
PANEL_SHOW_I TEM, 164, 179, 348 
PANEL_SHOW_MENU, 163, 346, 348 
PANEL_SHOW_MENU_MARK, 172, 350 
PANEL_SHOW_RANGE, 184, 351 
PANEL_SHOW_VALUE, 184, 351 
PANEL_SLIDER_WIDTH, 184, 351 
PANELJTEXT, 160 
PANEL_TOGGLE, 160 
PANEL_TOGGLE_VALUE, 350 
PANEL_VALUE, 162, 163, 185, 350, 351, 352 
PANEL__VALUE_DI SPLAY_LENGTH, 178, 352 
PANEL_VALUE_FONT, 351, 352 
PANEL_VALUE_STORED_LENGTH, 179, 352 
PANEL_VALUE_X, 162, 348 
PANEL_VALUE_Y, 162, 348 
panel data types 
Panel, 327 

Panel_attribute, 327 
Panel_item, 327 
Panel_setting, 327 
panel functions and macros, 353 

panel_accept_key (), 191, 353 
panel_accept_menu (), 191,353 
panel_accept_preview (), 191,353 
panel_advance_caret (), 180, 353 
panel_backup__caret (), 180, 353 


panel functions and macros, continued 

panel_begin_preview (), 191,353 
panel_button_image (), 168, 353 
panel_cancel__preview (), 191, 353 
panel_create_item (), 41, 160, 353 
panel_default_handle_event (), 190, 354 
panel_destroy_item (), 164, 354 
panel__each_item (), 354 
panel_event (), 194,354 
panel_get (), 163, 354 
panel_get_value (), 164 
panel_jpaint (), 185, 354 
panel_set (), 162, 354 
panel_set_value (), 162 
panel_text_notify (), 181, 354 
panel_update_preview (), 191, 355 
panel__update_scrolling_size (), 165, 355 
panel_window_event (), 194, 355 
panel item 

accepting selection, 189 
basic item types, 158 
button item, 158, 167 thru 169 
choice item, 158, 170 thru 176 
choice item “creep”, 161 
creation, 160 

cycle item description, 174 
default positioning, 161 
destroying, 164 
explicit positioning, 160 
item types for creation routine, 160 
layout of components, 162 
message item, 158,167 
modifying attributes, 162 
painting, 185 
positioning, 160 
previewing selection, 189 
retrieving attributes, 163 
slider item, 159, 184 thru 185 
table of choice and toggle item attributes, 349 
table of slider item attributes, 351 
table of text item attributes, 352 
text item, 159,178 thru 183 
toggle item, 159, 176 thru 178 
Panel_attribute, 327 
PANEL_EVENT__CANCEL, 190 
P ANEL_EVENT_DRAG__I N, 190 
PANEL_EVENT_MOVE_IN, 190 
PANEL_INSERT, 181 
Panel_item, 327 
PANEL_NEXT, 181 
PANEL_NONE, 181 
PANEL_PREVIOUS, 181 
Panel_setting, 327 

performance hints — locking and batching, 108 

perror(3), 305 

pipes, 290 

pixels, 103 

pixrect, 103 

pixwin, 101 

background color, 115 
batching, 109,110 
bitplane control, 120 
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pixwin, continued 

cgf our frame buffer, 124 
changing region size, 112 
clipping in a pixwin, 112 
clipping with regions, 112 
colormap, 118 
colormap manipulation, 113 
colormap name, 117 
destruction, 113 
determining region size, 112 
foreground color, 115 
interface summary, 356 
inverting colors, 119 
locking, 108, 109 

locking and batching interaction, 112 

performance hints, 109, 110 

plane groups, 124 

positioning, 52 

rasterop function, 104 

regions, 112 

rendering speed, 108 

retained regions, 112 

table of color manipulation functions, 360 

table of drawing functions, 356 

what is a pixwin?, 103 

write routines, 104 

writing text, 106 

pixwin functions and macros, 356 

pw_use__fast_monochrome (), 125 
pw_batch(), 111 
pw_batch_off (), 111,356 
pw_batch_on (), 111, 356 
pw_batchrop (), 106, 356 
pw_blackonwhite (), 119,360 
pw_char (), 105,356 
pw_close (), 113, 356 
pw_copy (), 108,356 
pw_cy c l ec °l° rma p (), 118, 360 
pw_dbl_access (), 123, 360 
pw_dbl_flip (), 123,360 
pw_dbl__get (), 124, 360 
pw_dbl_release (), 123, 360 
pw_dbl_set (), 124, 360 
pw_get (), 108, 356 
pw_get_region_rect (), 112, 356 
pw_getattributes (), 120, 360 
pw_getcmsname (), 117, 360 
pw_getcolormap (), 118, 360 
pw_getdefaulterns (), 361 
pw_line (), 107,357 
pw__lock (), 109,357 

PW _ 0P _ C0UNT ’ 111 
pw_pf sysclose (), 106, 357 

pw_pf sysopen (), 106,357 
pw_polygon__2 (), 107,357 
pw_polyline (), 107, 357 
pw_polypoint (), 105, 357 
pw_put (), 104, 357 
pw_putattributes (), 120, 361 
pw_putcolormap (), 118, 121, 361 
pw_read (), 108,358 
pw_region (), 112, 358 
pw_replrop (), 105, 358 
pw_reset (), 110, 358 


pixwin functions and macros, continued 
pw_reversevideo (), 119, 361 
pw_rop (), 104,358 
pw_set_region__rect (), 112, 358 
pw_setcmsname (), 117, 361 
pw_show (), 111, 358 
pw_stencil (), 106, 358 
pw_text (), 106, 359 
pw_traprop (), 107, 359 
pw_ttext (), 106, 359 
pw_unlock (), 109, 359 
pw_vector (), 105, 359 
pw__whiteonblack (), 119, 361 
pw_write (), 104, 359 
pw__writ©background (), 104, 359 
text routines, 105 
polling, 295 

pop-up windows, 16,44 thru 49 
blocking, 47 
example program, 389 
non-blocking, 46 
restrictions, 49 

porting programs to SunView, 303 

SunWindows-based, 477, see converting programs to Sun- 
View 

programmatic scrolling, 275 
pty (pseudo-tty), 57 
pw_batch, 111, 356 

R 

reading events, 97 
Rect struct, 52 

refusing the keyboard input focus, 88 
regions of a pixwin, 112 

registering an event handler with the Notifier, 288 
releasing the event lock, 97 
rendering speed, 108 
reserved namespaces, 30 

restrictions on use of UNIX facilities by SunView applications, 285 
row/column space in a window, 53 
example program, 406 

s 

sample programs, see example programs 
Scroll_motion, 327 
scrollbar, 267, 327 
basic usage, 272 
model, 269 

programmatic scrolling, 275 
SCROLLBAR default symbol, 272 
table of attributes, 362 
table of functions, 365 
thumbing, 271 
use with canvases, 64 
use with panels, 165 
user interface, 271 
scrollbar attributes, 362 

SCROLL_ABSOLUTE_CURSOR, 362 
SCROLL_ACTIVE_CURSOR, 362 
SCROLL_ADVANCED_MODE, 362 
SCROLL_BACKWARD_CURSOR, 362 
SCROLL BAR COLOR, 362 
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scrollbar attributes, continued 

SCROLL_BAR_DISPLAY_LEVEL, 362 
SCROLL_BORDER, 362 
SCROLL_BUBBLE_COLOR, 362 
SCROLL__BUBBLE__DI SPLAY_LEVEL, 362 
SCROLL_BUBBLE_MARGIN, 362 
SCROLLED I RECTI ON, 273, 362 
SCROLL__END_P 01 NT__AREA, 362 
SCROLL_FORWARD_CURSOR, 362 
SCROLL_GAP, 362 
SCROLL_HEIGHT, 272, 363 
SCROLL__LAST_VIEW_START, 275, 363 
SCROLL_LEFT, 363 
SCROLL_LINE_HEIGHT, 363 
SCROLL_MARGIN, 363 
SCROLL_MARK, 363 
SCROLL_NORMALIZE, 363 
SCROLL_NOTIFY_CLIENT, 363 
SCROLLJDB JECT, 363 
SCROLL_OB JECT_LENGTH, 269, 363 
SCROLL_PAGE_BUTTON_LENGTH, 363 
SCROLL_PAGE_BUTTONS, 363 
SCROLL_P AI NT_BUTT ON S_P ROC, 363 
SCROLL_PIXWIN, 363 
SCROLL_PLACEMENT, 272, 363 
SCROLL_RECT, 272, 363 
SCROLL_REPEAT_T I ME, 364 
SCROLL_REQUEST_MOTION, 364 
SCROLL_REQUEST_OFFSET, 364 
SCROLL_THICKNESS, 272, 273, 364 
SCROLL_TO_GRID, 364 
SCROLL_TOP, 364 
SCROLL_VIEW_LENGTH, 269, 364 
SCROLL_VIEW__ST ART, 269, 275, 364 
SCROLL_WI DTH, 272, 364 
scrollbar data types 

Scroll_motion, 327 
Scrollbar, 327 
Scrollbar__attribute, 327 
Scrollbar_attribute_value, 327 
Scrollbar_setting, 327 
scrollbar functions, 365 

scrollbar_clear_bubble(), 365 
scrollbar_create (), 165, 272, 365 
scrollbar_destroy (), 272 
scrollbar_get (), 272 
scrollbar_jpaint (), 365 
scrollbar_j>aint_bubble (), 365 
scrollbar_j?aint_clear (), 365 
scrollbar_scroll_to (), 275, 365 
scrollbar__set (), 272, 365 
Scrollbar_attribute, 327 
Scrollbar_attribute_value, 327 
Scrollbar_setting, 327 
selection of panel items 
buttons, 167 
choices, 172 
sliders, 184 
text, 179 
toggles, 176 
Selection Service, 279 
setting position of mouse cursor, 91 
Setting the contents of a Text Subwindow 


Setting the contents of a Text Subwindow, continued 
Setting contents, 140 
SHIFT_CAPSLOCK, 89 
SHIFT_CTRL, 89 
SHIFT__LEFT, 89 
SHIFT_LOCK, 89 
SHIFT_META, 89 
SHIFT_RIGHT, 89 
SHIFTMASK, 96, 97 
show color, 116 
SIGALRM, 286 
sigblock(2), 293 
SIGCHLD, 286 
SIGCONT, 285 
SIGIO, 286 
signal(3), 285,291 

Notifier-compatible version, 291 
signals — use with Notifier, 291 
SIGPIPE, 292 
SIGTERM, 286 
SIGURG, 88, 286 
sigvec(2), 285 
SIGVTALRM, 286 
slider panel item, 159, 184 thru 185 
stop key, 88 
subframe, 16 
subwindow layout 

discussion of image browser_1 program, 50 
example program, 401 
subwindows, 16 

changing layout dynamically, 52 
definition of, 19 
specifying layout, 51, 52 
specifying size, 50 
<suntool/canvas.h>, 61 
<suntool/icon. h>, 261 
< sunt ool/menu .h>, 221 
<suntool/panel,h>, 153 
<suntool/scrollbar .h>, 165,267 
<suntool/seln.h>, 279 
<suntool/sunview.h>, 27 
<suntool/textsw.h>, 129 
<suntool/tty.h>, 211 
Sun View 

changes in SunOS releases, 4 

code no longer supported, 5 

converting programs from SunWindows, 477 

data types, 324 

file descriptor limits, 57 

frame header, 18 

graphics standards in windows, 3 

history, 4 

interface outline, 27 
interface summary, 315 
libraries, 27 
model, 9 
objects, 9 
overview, 3 
plane groups, 126 
porting programs to, 303 
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SunView, continued 

reserved namespaces, 30 

restrictions on use of UNIX facilities by applications, 285 
source code of programs, 389 
standard functions for objects, 29 
summary of object types, 11 
<sunwindow/cms_mono .h>, 115 
<sunwindow/rect.h>, 52 
<sunwindow/win_cursor. h>, 253 
SunWindows 

converting programs to SunView, 477 
equivalent code in SunView, Table C-l 
system(3), 286 

system calls not to be used under SunView, 285 

T 

terminal emulator subwindow — see “tty sub window’ ’, 211 
text notification procedure 
default, 181 

possible return values, 181 
text panel item, 159, 178 thru 183 
text sub window, 129 

as a sequence of characters, 132 

attribute ordering, 132 

checking its status, 133 

concepts, 132 

creation, 132 

discarding edits, 139 

edit log, 138 

editing contents of, 136 

and the file system, 138 

finding text, 144 

getting a text selection, 132 

insertion point, 132,135,136,137 

interface summary, 366 

manipulating the backing store, 136 

marking text, 145 

matching a span of characters, 144 

matching a specific pattern, 144 

multiple views, 147 

notification, 148 

overflow of edit log, 138 

positioning the caret, 135 

positioning the text, 141 

reading from, 135 

saving edits, 139 

setting selection, 147 

storing edits, 139 

table of attributes, 366 

table of functions, 372 

table of Text sw_act ion attributes, 149, 370 
table of Textsw_status values, 134, 371 
writing to, 134 

text subwindow attributes, 366 

TEXTSW__AD JUST_IS_PENDING__DELETE, 366 

TEXTSW_AGAIN_RECORD ING, 366 

TEXTSW_AUTO_INDENT, 366 

TEXTSW__AUTO_SCROLL_BY, 366 

TEXTSW__BLINK_CARE T, 366 

TEXTSW_BROWSING, 366 

TEXTSW_CHECKPOINT_FREQUENCY, 366 

TEXTSW__CL IENT_DAT A, 366 

TEXTSW CONFIRM OVERWRITE, 366 


text subwindow attributes, continued 

TEXTSW_CONTENTS, 135, 139, 366 
TEXTSW__CONTROL_CHARS_USE_FONT, 366 
TEXTSW_D I SABLE_CD, 366 
TEXTSW_D I SABLE_LOAD, 367 
TEXTSWJEDIT__COUNT, 367 
TEXTSW_FILE, 46, 133, 367 
TEXTSW_FILE_CONTENTS, 367 
TEXTSW_FIRST, 133, 142, 367 
TEXTSW_FIRST_LINE, 142, 367 
TEXTSW_H I STORY__LIMIT, 367 
TEXTSW_I GNORE_LIMI T, 367 
TEXTSW_I NSERT__FROM_F I LE, 367 
TEXTSW__INSERT_MAKES__VISIBLE, 367 
TEXTSW_INSERTION_POINT, 135, 367 
TEXTSW_LEFT_MARGIN, 367 
TEXTSW_LENGTH, 132, 367 
TEXTSW__L INE_BREAK_ACT I ON, 367 
TEXTSW_LOWER_CONTEXT, 367 
TEXTSW_MARK_DEFAULTS, 145 
TEXTSW_MARK_MOVE_AT_INSERT, 145 
TEXTSW_MEMORY_MAXIMUM, 138, 368 
TEXTSW_MENU, 368 
TEXTSW_MOD IFI ED, 133, 368 
TEXTSW_MULTI_CLICK_SPACE, 368 
TEXTSW_MULTI_CLI CK_TIMEOUT, 368 
TEXTSW_NOTIFY_PROC, 148, 368 
TEXTSW_READ_ONLY, 368 
TEXTSW_SCROLLBAR, 368 
TEXTSW_STATUS, 132, 133, 368 
TEXTSW_STORE_CHANGES_FI LE, 368 
TEXTSW_STORE_SELF_IS_SAVE, 368 
TEXTSW_UPDATE_SCROLLBAR, 369 
TEXTSW_UPPER_CONTEXT, 369 
text subwindow constants 

TEXTSW_I NFINITY, 135, 136, 137 
TEXTSW_UNIT_IS_CHAR, 136 
TEXTSW_UNIT_IS_LINE, 136 
text subwindow data types 
Textsw, 327 

Textsw_index, 132, 327 
Textsw_status, 133,327 
text subwindow functions, 372 

textsw_add_mark (), 145, 372 
textsw__append_file_name (), 138, 372 
textsw__delete (), 136, 372 
textsw__edit (), 136, 372 
textsw_erase (), 136, 372 
textsw_f ile_lines_visible (), 143, 372 
textsw_f indjbytes (), 144, 372 
textsw_f ind__mark (), 146,373 
textsw_first (), 147, 373 
textsw_index_for_f ile__line (), 142,373 
textsw_insert (), 134, 373 
textsw_match_bytes (), 144, 373 
textsw__next (), 147,373 
textsw_normalize_view (), 143, 373 
textsw_j?ossibly_normalize (), 143, 373 
textsw_remove_rnark (), 146, 374 
textsw_replace_bytes (), 137, 374 
textsw__reset (), 139, 150, 374 
textsw_save (), 139,150,374 
textsw_screen_line__count (), 143,374 
textsw scroll_lines (), 142,374 
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text subwindow functions, continued 

text sw_set_selection (), 147, 374 
textsw_store (), 150 
textsw_store_f ile (), 139,375 
Textsw, 327 
Text sw_act ion, 148 
Text sw__action attributes, 370, 149 

TEXTSW_ACTION_CAPS_LOCK, 149, 370 
TEXT SW_ACT I ON_CHANGED_D I RECTORY, 149, 370 
TEXTSW_ACTION_EDITED_FILE, 149, 370 
TEXT SW_ACTION_FILE__I S_READONLY, 149, 370 
TEXT SW_ACT I ON_LOADE D_F I LE, 149, 370 
TEXT SW_ACTION_EDITED_FILE, 150 
TEXT SW_ACTION_LOADED_FILE, 150 
TEXTSW_ACTION_TOOL_CLOSE, 149, 370 
TEXTSW_ACTION_TOOL_DESTROY, 149, 370 
TEXT SW_ACT I ON_TOOL_MGR, 149, 370 
TEXTSW_ACTION_TOOL_QUI T, 149, 370 
TEXT SW_ACT I ON_US I NG_MEMORY, 149, 370 
Text sw__index, 132, 327 
TEXT S W_I NFINIT Y, 135, 136, 137 
Textsw_status, 133, 327 
Textsw_status values, 371, 134 

TEXT SW_STATUS_BAD_ATTR, 134, 371 
TEXTSW_STATUS__BAD_ATTR_VALUE, 134, 371 
TEXT SW_STATUS_CANNOT_ALLOCATE, 134, 371 
TEXT SW_STATUS_CANNOT_I NSERT_FROM_F ILE,: 

371 

TEXT SW_STATUS_CANNOT__OPEN__I NP UT, 134, 371 
TEXTSW_STATUS_OKAY, 134, 371 
TEXT SW_STATUS_OTHER_ERROR, 134, 371 
TEXTSW__STATUS_OUT_OF_MEMORY, 134, 371 
TEXT SW_UN I T_I S_CHAR, 136 
TEXT S W__UN I T__I S_L INE , 136 
timeout events, 294 
toggle panel item, 159, 176 thru 178 

translating events from canvas space to window space, 70, 98 
translating events from panel space to window space, 193 
tty subwindow 
creating, 213 

differences with Sun console, 214 
example program, 412 
example program to list files, 42 
file descriptor, 215 
input/output to tty subwindow, 213 
interface summary, 376 
monitoring, 215 
overview, 211 
reading and writing, 215 
special escape sequences, 215 
standard escape sequences, 214 
table of functions, 376 
table of special escape sequences, 377 
tty subwindow attributes 

TTY__ARGV, 213, 215, 216, 376 
TTY_CONSOLE, 376 
TTY_PAGE_MODE, 376 
TTY_QUI T_ON_CH I LD_DEATH, 376 
tty subwindow functions, 376 
example program, 412 
ttysw_input (), 42, 213, 376 
ttysw_output (), 214, 376 


u 

UNIX system calls and SunView 
alarm(3), 285 
f cntl(2), 286, 290 
f ree(3), 311 
getitimer(2), 285 
I/O in a tty subwindow, 215 
ioctl(2), 286 
perror(3), 305 
sigblock(2), 293 
signal(3), 285, 291 
sigvec(2), 285 
system calls not to be used, 285 
wait(2), 286 
wait3(2), 285, 288 

v 

views in text subwindows, 147 
Virtual User Input Device ( VUID ), 80 

w 

wait(2), 286 
wait3(2), 285, 288 
WIN_ASC I I_EVENTS, 90, 333 
WIN_EXTEND_TO_EDGE, 50, 51 
WIN_IN_TRANSIT_EVENTS, 90, 333 
WIN_LEFT_KEYS, 90, 333 
WIN_MOUSE_BUTTONS, 90, 333 
WIN_NO_EVENTS, 90, 333 
WI N_REPAI NT, 87 
WIN_RESIZE, 87 
WIN_RIGHT_KEYS, 90, 333 
WIN_STOP, 88 
WIN_TOP_KEYS, 90, 333 
WIN_UP_ASCII_EVENTS, 90, 333 
WIN_UP_EVENTS, 90, 333 
window, 33 

classes of windows, 16 
creation, 35 
destruction, 36 

initiating event processing, 35 
interface summary, 379 
limit to number of windows, 57 
simplest SunView program, 37 
table of attributes, 379 
table of functions and macros, 384 
table of input-related window attributes, 334 
window attributes, 379 
WIN_BELOW, 379 
WIN_BOTTOM_MARGIN, 53, 379 
WIN_CLIENT_DATA, 379 
WIN_COLUMN_GAP, 53, 379 
WIN_COLUMN_WI DTH, 53, 379 
WIN_COLUMNS, 50, 159, 379 
WI N_CONS UME_KBD_EVENT, 70, 379 
WIN_CONSUME_KBD_EVENTS, 379 
WIN_CONSUME_PICK_EVENT, 379 
WIN_CONSUME_PICK_EVENTS, 379 
WIN_CURSOR, 255, 256, 379 
WIN_DEVICE_NAME, 379 
WIN_DEVI CE_NUMBER, 379 
WIN ERROR_MSG, 40, 379 


-500- 




Index — Continued 


window attributes, continued 

WIN_EVENT_PROC, 70, 81, 379 
WIN_EVENT_STATE, 96, 379 
WIN_FD, 379 

WIN_FIT_HEIGHT, 41, 379 
WIN_FIT_WIDTH, 41, 380 
WIN_FONT, 41,160, 309, 380 
WIN_GRAB_ALL_INPUT, 92, 380 
WIN_HEIGHT, 159, 380 

WIN_HORIZONTAL_SCROLLBAR, 165, 267, 380 

WIN_IGNORE_KBD_EVENT, 380 

WIN_IGNORE_KBD_EVENTS, 380 

WIN_IGNORE_PICK_EVENT, 380 

WIN_IGNORE_PICK_EVENTS, 380 

WI N_INPOT_DESIGNEE, 92, 380 

WIN_KBD_FOCUS, 380 

WIN_KBD_INPOT_MASK, 380 

WIN_KEYBOARD_F OCUS, 91 

WIN_LEFT_MARGIN, 53, 380 

WIN_MENU, 380 

WIN_MOUSE_XY, 91, 380 

WIN_NAME, 380 

WIN_OWNER, 380 

WIN_PERCENT_HEIGHT, 380 

WI N_PERCENT_WI DTH, 381 

WIN_PICK_INPUT_MASK, 381 

WIN_PIXWIN, 65, 103, 381 

WIN_RECT, 52, 381 

WIN_RIGHT_MARGIN, 53,381 

WIN_RIGHT_OF, 381 

WIN_ROW_GAP, 53,381 

WI N_ROW_HE I GHT, 53, 381 

WIN_ROWS, 50,159, 381 

WIN_SCREEN_RECT, 381 

WIN_SHOW, 46, 381 

WIN_TOP_MARGIN, 53, 381 

WIN_TYPE, 381 

WIN_VERTICAL_SCROLLBAR, 165, 267,381 
WIN_WIDTH, 159,381 
WIN_X, 52, 381 
WIN_Y, 52, 381 

window classes 
base frame, 16 
frame, 16 
pop-up, 16 
subframe, 16 
subwindow, 16 

window functions and macros, 384 
window_bell (), 384 
window_create (), 35, 63, 297,384 
window_default_event_proc (), 81, 384 
window_destroy (), 36,384 
window_done (), 36, 384 
window_fit (),384 
window_fit_height (), 41, 
window_f it_width (), 41, 384 
window_get (), 35, 384 
window_loop (), 48, 385 
window_main_loop (), 35, 303, 385 
window_read_event (), 71, 97, 193, 385 
window_refuse_kbd_focus (), 88, 385 
window_release_event_lock (), 97, 385 
window_return (), 48, 385 
window set (), 35,162,385 


-501- 








Notes 






Notes 






Notes 






Notes 








Notes 





Notes 






Notes 












